Device Requests

📘

This page is a work in progress

This group of REST API allows performing generic requests to a remote device.

Perform a Request

The following API will send a request message to the given remote device. This call is generally used to perform remote management of resources attached to the device such sensors and registries.

POST /{scopeId}/devices/{deviceId}/requests

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 the optional timeout query parameter, an integer value which represents the timeout for the request in milliseconds.

Body

This call have a required body parameter that defines an object containing the input request to be performed on the remote device. As an example:

{
  "channel": {
    "type": "genericRequestChannel",
    "method": "EXECUTE",
    "appName": "CMD",
    "version": "V1",
    "resources": [
      "command"
    ]
  },
  "payload": {
    "metrics": [
      {
        "valueType": "string",
        "value": "sleep",
        "name": "command.command"
      },
      {
        "valueType": "string",
        "value": "180",
        "name": "command.argument"
      }
    ]
  }
}

Response

The response of this call will contain the list of the request installed on the given device. As an example:

{
  "capturedOn": "2019-09-13T13:53:09.447Z",
  "channel": {
    "appName": "CMD",
    "version": "V1"
  },
  "payload": {
    "metrics": [
      {
        "valueType": "string",
        "value": "false",
        "name": "command.timedout"
      },
      {
        "valueType": "string",
        "value": "sleep: missing operand\nTry 'sleep --help' for more information.\n",
        "name": "command.stderr"
      },
      {
        "valueType": "string",
        "name": "kapua.response.exception.stack"
      },
      {
        "valueType": "string",
        "name": "kapua.response.exception.message"
      },
      {
        "valueType": "string",
        "value": "1",
        "name": "command.exit.code"
      },
      {
        "valueType": "string",
        "value": "",
        "name": "command.stdout"
      },
      {
        "valueType": "string",
        "value": "200",
        "name": "response.code"
      }
    ]
  },
  "receivedOn": "2019-09-13T13:53:09.466Z",
  "scopeId": "AQ",
  "sentOn": "2019-09-13T13:53:09.447Z"
}