Streaming to a host:port Endpoint

Set up REST streaming to any cloud

Creating a Cloud Connector from ThingSpace to any cloud endpoint using REST streaming

This page describes how to set up REST streaming from ThingSpace to a remote endpoint specified by a host:port combination. ThingSpace will stream data from your devices to the endpoint so that you can use that data in your IoT applications.

Prerequisites:

  • A Verizon BillingAccount with CAS devices previously on boarded into it

  • Ability to create the access (user token) and the session (VZ M2M token) to execute the ThingSpace API

  • API reference documentation: https://thingspace.verizon.com/resources/documentation/cloudconnector/API_Reference/

  • An HTTPS server listening for REST streaming events

  • Perform the Query Subscription and Query Target API calls to make sure that there are no existing subscriptions and/or targets associated with the Verizon BillingAccountId

  • Delete any previously created subscription on the Verizon BillingAccount

  • Delete any previously created targets on the Verizon BillingAccount

 

Setting up streaming requires only two steps in ThingSpace:

  1. Create a target resource that is configured to stream data to your endpoint.

  2. Create a subscription that defines the data to send.

Create a target to define the Endpoint

Create a target resource to define where to send device data. 

A REST streaminghost:port target requires these values:

  • The ThingSpace billing account associated with the CAS devices

  • addressscheme must be “streamrest”.

  • address is the host:port where your application is ready to receive streamed device data.

  • name to query for resources later.

 

If the cloud HTTPS server requires authentication for streaming events, the following authentication parameters are available (but optional from Cloud Connector perspective):

  • Basic authorization (base 64 encoded username and password)

  • oAuth 2.0:

    • Access token

    • Refresh token

    • Refresh URL to refresh the access token

    • ClientID

    • Secret

    • Scope

 

See create a target resource for no authorization and oAuth 2.0 authorization examples.

Create a Subscription to define what to send

Create a subscription resource that defines the data to send to the target.

  • email is the email address to which any error reports should be delivered.

  • streamkind must be ts.event to receive all device data. Alternatively, you can set it to ts.event.diagnostics or ts.event.security to only receive events of those specific types.

  • targetid must be the ID of the target that you created in the previous step. You can find the ID in the response to the POST /targets request.

  • name to be used when querying for the subscription later.

 

Once you have created a target and a subscription that uses the target ID, ThingSpace will start streaming data from your devices to the defined endpoint each time data is received from a device.

Device data format

The data format that you’ll receive depends on what your devices are configured to send. This is a sample of data from a Verizon Critical Asset Sensor:

{
   "kind":"ts.event",
   "action":"create",
   "data":{
      "action":"update",
      "createdon":"2019-02-13T00:20:20Z",
      "deviceid":"8461f530-2e31-6e87-e357-6c38251d4d01",
      "fields":{
         "location":{
            "latitude":"37.2315521",
            "longitude":"-119.4690322"
         }
      },
      "foreignid":"e1f15861-7de7-69cb-ed7d-b4a92e091bc4",
      "id":"858122e9-77c6-6832-fec7-1bfa81a62425",
      "kind":"ts.event",
      "lastupdated":"2019-02-13T00:20:59.547536166Z",
      "state":"update",
      "transactionid":"864508030084997-OnBoard-fdfbe471-647e-4296-bfe1-a861b0b0ffe7",
      "version":"1.0",
      "versionid":"3d03f3a2-2f25-11e9-a77f-02420a5b1b0d"
   }
},
{
  "kind": "ts.event",
  "action": "create",
  "data": {
      "action": "update",
      "createdon": "2019-02-13T00:20:20Z",
      "deviceid": "8461f530-2e31-6e87-e357-6c38251d4d01",
      "fields": {
          "battery": "97"
      },
      "foreignid": "e1f15861-7de7-69cb-ed7d-b4a92e091bc4",
      "id": "c5f189f0-df17-69a1-e125-d63cf21194a0",
      "kind": "ts.event",
      "lastupdated": "2019-02-13T00:20:43.605369487Z",
      "state": "update",
      "transactionid": "864508030084997-OnBoard-86f1bf8a-2a8f-43da-b310-71208319b947",
      "version": "1.0",
      "versionid": "33835ec1-2f25-11e9-8786-02420a611e11"
  }
},
{
  "kind": "ts.event",
  "action": "create",
  "data": {
      "action": "update",
      "createdon": "2019-02-13T00:20:20Z",
      "deviceid": "8461f530-2e31-6e87-e357-6c38251d4d01",
      "fields": {
          "humidity": "25"
      },
      "foreignid": "e1f15861-7de7-69cb-ed7d-b4a92e091bc4",
      "id": "a5d19d9d-1390-6a9a-ea6b-fd71e04ac8b4",
      "kind": "ts.event",
      "lastupdated": "2019-02-13T00:20:41.603693478Z",
      "state": "update",
      "transactionid": "864508030084997-OnBoard-b36ab8a9-ac0a-412e-9c2a-e7df9214686b",
      "version": "1.0",
      "versionid": "3251f048-2f25-11e9-b387-02420a631b19"
  }
}