Device Operations

πŸ“˜

This page is a work in progress

This group of REST API allows tracking asynchronous operations on a remote device.

Get all the Device Registry Operations

The following API allows one to retrieve all the asynchronous operations on the given device:

GET /{scopeId}/devices/{deviceId}/operations

The required path parameters to be used with this call are:

  • {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
  • {deviceId} is the id of the desired device.

It is also possible to add optional query parameters :

  • resource is a string value that represents the resource of the operation in which to search the results;
  • offset is an integer value which represents the result set offset;
  • limit is an integer value which represents the result set limit.

For instance:

GET /{scopeId}/devices/{deviceId}/operations?resource={resource_value}&offset={offset_value}&limit={limit_value}

Response

The response of this call represents the list of all the device management registry asynchronous operations on the given device. As an example:

{
  "type": "deviceManagementOperationListResult",
  "limitExceeded": false,
  "size": 1,
  "items": [
    {
      "type": "deviceManagementOperation",
      "id": "cjmXXKvLUY8",
      "scopeId": "AQ",
      "createdOn": "2019-11-15T11:27:24.857Z",
      "createdBy": "AQ",
      "modifiedOn": "2019-11-15T11:30:01.975Z",
      "modifiedBy": "Ag",
      "optlock": 3,
      "action": "EXECUTE",
      "appId": "DEPLOY",
      "deviceId": "UVjeGkGVT3A",
      "endedOn": "2019-11-15T11:30:01.568Z",
      "operationProperties": [
        {
          "name": "kapau.package.download.file.type",
          "propertyType": "string",
          "propertyValue": "DEPLOYMENT_PACKAGE"
        },
        {
          "name": "kapau.package.download.password",
          "propertyType": "string",
          "propertyValue": "kapua-password"
        },
        {
          "name": "kapau.package.download.username",
          "propertyType": "string",
          "propertyValue": "kapua-sys"
        },
        {
          "name": "kapua.package.download.block.delay",
          "propertyType": "integer",
          "propertyValue": "1000"
        },
        {
          "name": "kapua.package.download.block.size",
          "propertyType": "integer",
          "propertyValue": "128"
        },
        {
          "name": "kapua.package.download.block.timeout",
          "propertyType": "integer",
          "propertyValue": "60000"
        },
        {
          "name": "kapua.package.download.install",
          "propertyType": "boolean",
          "propertyValue": "true"
        },
        {
          "name": "kapua.package.download.name",
          "propertyType": "string",
          "propertyValue": "heater"
        },
        {
          "name": "kapua.package.download.uri",
          "propertyType": "java.net.URI",
          "propertyValue": "http://download.eclipse.org/kura/releases/4.1.0/org.eclipse.kura.demo.heater_1.0.500.dp"
        },
        {
          "name": "kapua.package.download.version",
          "propertyType": "string",
          "propertyValue": "1.0.500"
        },
        {
          "name": "kapua.package.operation.id",
          "propertyType": "org.eclipse.kapua.commons.model.id.KapuaEid",
          "propertyValue": "2588799701293395515"
        },
        {
          "name": "kapua.package.reboot",
          "propertyType": "boolean",
          "propertyValue": "false"
        }
      ],
      "log": "",
      "operationId": "I-1DnL467js",
      "resource": "DOWNLOAD",
      "startedOn": "2019-11-15T11:27:24.842Z",
      "status": "COMPLETED"
    }
  ]
}

Get a single Device Registry Operation

The following API allows one to retrieve a specific asynchronous operation on the given device:

GET /{scopeId}/devices/{deviceId}/operations/{operationId}

The required path parameters to be used with this call are:

  • {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
  • {deviceId} is the id of the desired device;
  • {operationId} is the id of the Registry Operation to retrieve.

Response

The response of this call represents the details of the requested asynchronous operation on the given device. As an example:

{
  "type": "deviceManagementOperation",
  "id": "cjmXXKvLUY8",
  "scopeId": "AQ",
  "createdOn": "2019-11-15T11:27:24.857Z",
  "createdBy": "AQ",
  "modifiedOn": "2019-11-15T11:30:01.975Z",
  "modifiedBy": "Ag",
  "optlock": 3,
  "action": "EXECUTE",
  "appId": "DEPLOY",
  "deviceId": "UVjeGkGVT3A",
  "endedOn": "2019-11-15T11:30:01.568Z",
  "operationProperties": [
    {
      "name": "kapau.package.download.file.type",
      "propertyType": "string",
      "propertyValue": "DEPLOYMENT_PACKAGE"
    },
    {
      "name": "kapau.package.download.password",
      "propertyType": "string",
      "propertyValue": "kapua-password"
    },
    {
      "name": "kapau.package.download.username",
      "propertyType": "string",
      "propertyValue": "kapua-sys"
    },
    {
      "name": "kapua.package.download.block.delay",
      "propertyType": "integer",
      "propertyValue": "1000"
    },
    {
      "name": "kapua.package.download.block.size",
      "propertyType": "integer",
      "propertyValue": "128"
    },
    {
      "name": "kapua.package.download.block.timeout",
      "propertyType": "integer",
      "propertyValue": "60000"
    },
    {
      "name": "kapua.package.download.install",
      "propertyType": "boolean",
      "propertyValue": "true"
    },
    {
      "name": "kapua.package.download.name",
      "propertyType": "string",
      "propertyValue": "heater"
    },
    {
      "name": "kapua.package.download.uri",
      "propertyType": "java.net.URI",
      "propertyValue": "http://download.eclipse.org/kura/releases/4.1.0/org.eclipse.kura.demo.heater_1.0.500.dp"
    },
    {
      "name": "kapua.package.download.version",
      "propertyType": "string",
      "propertyValue": "1.0.500"
    },
    {
      "name": "kapua.package.operation.id",
      "propertyType": "org.eclipse.kapua.commons.model.id.KapuaEid",
      "propertyValue": "2588799701293395515"
    },
    {
      "name": "kapua.package.reboot",
      "propertyType": "boolean",
      "propertyValue": "false"
    }
  ],
  "log": "",
  "operationId": "I-1DnL467js",
  "resource": "DOWNLOAD",
  "startedOn": "2019-11-15T11:27:24.842Z",
  "status": "COMPLETED"
}

Delete a single Registry Operation

The following API allows one to delete a specific asynchronous operation on the given device:

DELETE /{scopeId}/devices/{deviceId}/operations/{operationId}

The required path parameters to be used with this call are:

  • {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
  • {deviceId} is the id of the desired device;
  • {operationId} is the id of the Registry Operation to delete.

Response

The response of this call will consist in an HTTP 200 status code in case the operation has been successfully deleted.

Query the Registry Operations

The following API allows one to query the registry operations on the given device:

POST /{scopeId}/devices/{deviceId}/operations/_query

The required path parameters to be used with this call are:

  • {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
  • {deviceId} is the id of the desired device.

Body

This call have a required body parameter that defines an object to filter the query results. As an example:

{
  "offset": 0,
  "limit": 50
}

Response

The response of this call represents the results of the query on the given device. As an example:

{
  "type": "deviceManagementOperationListResult",
  "limitExceeded": false,
  "size": 1,
  "items": [
    {
      "type": "deviceManagementOperation",
      "id": "cjmXXKvLUY8",
      "scopeId": "AQ",
      "createdOn": "2019-11-15T11:27:24.857Z",
      "createdBy": "AQ",
      "modifiedOn": "2019-11-15T11:30:01.975Z",
      "modifiedBy": "Ag",
      "optlock": 3,
      "action": "EXECUTE",
      "appId": "DEPLOY",
      "deviceId": "UVjeGkGVT3A",
      "endedOn": "2019-11-15T11:30:01.568Z",
      "operationProperties": [
        {
          "name": "kapau.package.download.file.type",
          "propertyType": "string",
          "propertyValue": "DEPLOYMENT_PACKAGE"
        },
        {
          "name": "kapau.package.download.password",
          "propertyType": "string",
          "propertyValue": "kapua-password"
        },
        {
          "name": "kapau.package.download.username",
          "propertyType": "string",
          "propertyValue": "kapua-sys"
        },
        {
          "name": "kapua.package.download.block.delay",
          "propertyType": "integer",
          "propertyValue": "1000"
        },
        {
          "name": "kapua.package.download.block.size",
          "propertyType": "integer",
          "propertyValue": "128"
        },
        {
          "name": "kapua.package.download.block.timeout",
          "propertyType": "integer",
          "propertyValue": "60000"
        },
        {
          "name": "kapua.package.download.install",
          "propertyType": "boolean",
          "propertyValue": "true"
        },
        {
          "name": "kapua.package.download.name",
          "propertyType": "string",
          "propertyValue": "heater"
        },
        {
          "name": "kapua.package.download.uri",
          "propertyType": "java.net.URI",
          "propertyValue": "http://download.eclipse.org/kura/releases/4.1.0/org.eclipse.kura.demo.heater_1.0.500.dp"
        },
        {
          "name": "kapua.package.download.version",
          "propertyType": "string",
          "propertyValue": "1.0.500"
        },
        {
          "name": "kapua.package.operation.id",
          "propertyType": "org.eclipse.kapua.commons.model.id.KapuaEid",
          "propertyValue": "2588799701293395515"
        },
        {
          "name": "kapua.package.reboot",
          "propertyType": "boolean",
          "propertyValue": "false"
        }
      ],
      "log": "",
      "operationId": "I-1DnL467js",
      "resource": "DOWNLOAD",
      "startedOn": "2019-11-15T11:27:24.842Z",
      "status": "COMPLETED"
    }
  ]
}

Count the Registry Operations

The following API allows one to count the registry operations on the given device:

POST /{scopeId}/devices/{deviceId}/operations/_count

The required path parameters to be used with this call are:

  • {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
  • {deviceId} is the id of the desired device.

Body

This call have a required body parameter that defines an object to filter the count result. As an example:

{
  "offset": 0,
  "limit": 50
}

Response

The response of this call represents the number of the matching operations on the given device. As an example:

{
  "count": 0
}