POST /devices/attributes/actions/observe/

Requests Diagnostics observation information via live periodic interval streaming of RF parameters from a list of IOT devices.

Contents

• Start Diagnostics Observation:
  POST /devices/attributes/actions/observe/
  • Uses and Requirements
  • Request Components
    • HTTP Request
    • Resource Path and Query Parameters
    • Header Parameters
    • Request Body
      • Example Request Body
  • Success Responses
    • Example Success Response
  • Asynchronous Callback
    • Example Callback Success Response
    • Example Callback when device is unable to start observation, with an error
  • Failure Responses

Uses and Requirements

This API will return (POST) callbacks, including the device identity, the attribute names, corresponding attribute values and the date/timestamp of when the observation was made for the attributes listed in the callback.

An RF attribute of the device can be streamed via periodically reported data. The highest frequency of reporting is 15 seconds. There is no upper limit on this time interval; however, for devices that are configured to sleep, this interval should be set less than the active timer for the device. Also streaming can be requested for a certain total duration of time. For the API, there is no limit to the maximum duration of monitoring. Monitoring will stop when one of these two occurs (whichever occurs first):

• The specified monitoring duration is met;
• Or the monthly allowance is met.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/diagnostics/v1/devices/attributes/actions/observe

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Request Body

Example Request Body

{
  "accountName": "TestQAAccount",
  "devices": [
    {
      "id": "864508030026238",
      "kind": "IMEI"
    }
  ],
  "attributes": [
      {
    "name": "RADIO_SIGNAL_STRENGTH"
      },
      {
    "name": "LINK_QUALITY"
     },
     {
    "name":"NETWORK_BEARER"
     },
    {
    "name":"CELL_ID"
    }
  ],
  "frequency": {
    "value": 15,
    "unit": "SECOND"
  },
  "duration": {
    "value": 15,
    "unit": "SECOND"
  }
}

Success Responses

Status 200

Example Success Response

{
    "createdOn": "2019-09-10T19:05:33.330579352Z",
    "transactionID": "9c7bb124-11f5-4ff3-8a88-0eec1ba99205",
    "status": "CANCEL_OBSERVE_PENDING"
}

Asynchronous Callback

Example Callback Success Response

{
   "accountName":"0642233522-00003",
   "attributes":[
      {
         "error":{

         },
         "name":"RADIO_SIGNAL_STRENGTH",
         "status":"OBSERVE_READY",
         "updatedOn":"2020-02-21T20:54:16.263Z",
         "value":"27"
      }
   ],
   "createdOn":"2020-02-21T20:54:16.263Z",
   "device":{
      "id":"355154080648401",
      "kind":"IMEI"
   },
   "error":{

   },
   "transactionID":"7c2d1d71-0b50-4d8a-ab13-aeb733d5e909"
}

Example Callback when device is unable to start observation, with an error

{
   "transactionID":"1b24047e-f35e-4d3e-aa60-675914fcbb15",
   "accountName":"0642233522-00003",
   "device":{
      "id":355154080648401,
      "kind":"IMEI"
   },
   "attributes":[
      {
         "updatedOn":"2020-03-20 04:00:29.1488572 +0000 UTC",
         "name":"RADIO_SIGNAL_STRENGTH",
         "value":"",
         "error":{
            "errorCode":"INTERNAL_SYSTEM_ERROR",
            "errorMessage":"9000, Internal system error"
         },
         "status":"OBSERVE_FAILURE"
      }
   ],
   "error":{
      "errorCode":"INTERNAL_SYSTEM_ERROR",
      "errorMessage":"9000, Internal system error"
   },
   "createdOn":"2020-03-20 04:00:29.148856888 +0000 UTC"
}

Failure Responses

Status 400 All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.

Try It Out!