This is an old revision of the document!
subscribe
Request a websocket data stream, and commands to manage the data stream
Description
Request ticket and meta data:
https://api.eze.io/v1/subscribe/ticket
The subscribe/ticket
call requests a websocket ticket and returns metadata for the group and ezeio units that are in context of the given API credentials.
Subsequent calls using the subscribe command are used to manage the data stream.
Parameters
The subscribe/ticket
call has no parameters
Example usage
Using the subscribe API requires the following steps:
Step 1 : Request ticket and metadata
Call the following API endpoint using valid API credentials:
https://api.eze.io/v1/subscribe/ticket
This call will return a JSON object (see example below) with metadata listing the systems that will be accessible through the websocket.
(whitespaces added for readability)
{ "reqtime": "2021-01-31T14:15:16Z", "ws": "wss:\/\/api.eze.io\/ws\/wstktXXXXXXXXXXXXXXXXXXXXXXX", "api": "https:\/\/api.eze.io\/v1\/subscribe\/wstktXXXXXXXXXXXXXXXXXXXXXXX\/", "account": { "id": "123", "name": "eze System", "description": "eze System - Testaccount" }, "systems": [{ "serial": "ABC-123", "name": "Demo unit", "note": "This is a demo unit in our lab", "lastseen": "2021-01-31T14:10:11Z", "fields": [{ "fieldno": "1", "name": "Tank Level: Distance from top", "unit": "in", "decimals": "2", "assettag": "TANKLVL", "loginterval": "0" }, { "fieldno": "2", "name": "Output flow", "unit": "gal/min", "decimals": "1", "assettag": "", "loginterval": "60" }] }, { "serial": "ABC-456", "name": "Other demo unit", "note": "This is also a demo unit in our lab", "lastseen": "2021-01-31T14:09:56Z", "fields": [{ "fieldno": "2", "name": "Air temperature", "unit": "F", "decimals": "1", "assettag": "", "loginterval": "300" }, { "fieldno": "3", "name": "Relative humidity", "unit": "percent", "decimals": "0", "assettag": "", "loginterval": "0" }, { "fieldno": "4", "name": "Voltage", "unit": "V", "decimals": "1", "assettag": "V", "loginterval": "0" }] } ], "status": "OK", "exec_time": 0.055 }
The ws
property is the complete websocket URI. This URI is valid only for 10 seconds following the call to subscribe/ticket.
Step 2 : Open websocket and start receiving data
Use the ws
URI from step 1 to open a websocket connection.
The websocket will automatically receive all updates to any system (ezeio) covered by the initial API call, as the data becomes available to the cloud servers.
The data received will have a type
, describing what kind of data this is:
LOGDATA | The field data is from the 'fast log'. The interval is determined by the log interval setting on each field. |
STATUS | The field data is from the 'status log'. The interval is fixed to 10 minutes. |
Note that the ezeio normally buffers data before the data is uploaded to the cloud servers, so the data may be delayed with up to 20 minutes
The STATUS updates will be sent every 10 minutes even if a faster subscription is active.
Step 3 : Request subscription changes
With an open websocket and while receiving data from the ezeio system, you can call the subscribe API to request immediate updates or to cancel updates from a certain ezeio.
To request fast updates, the call is:
https://api.eze.io/v1/subscribe/wstktXXXXXXXXXXXXXXXXXXXXXXX/!ABC123
To cancel updates, the call is:
https://api.eze.io/v1/subscribe/wstktXXXXXXXXXXXXXXXXXXXXXXX/-ABC123
Multiple requests can be sent in the same command:
https://api.eze.io/v1/subscribe/wstktXXXXXXXXXXXXXXXXXXXXXXX/-ABC123,!ABC124,!ABC321,-ABC322