How to subscribe to nodes of the ctrlX Data Layer using REST commands via CURL

CodeShepherd · ‎11-30-2023

Content

This article shows how to subscribe to nodes of the ctrlX Data Layer via its web interface using REST commands in CURL. See general description and further information in our online documentation ctrlX OS, Operating System for ctrlX CORE Control Devices 02VRS, Application Manual -> ctrlX Data La...

Requirements

Connection to a ctrlX CORE hardware, ctrlX OS or ctrlX WORKS installed on a PC

Authorize

To get a valid web token send a https POST request to the authorization server of the ctrlX CORE "/identity-manager/api/v1/auth/token". The payload has to be a permitted user and a password written as a JSON (JavaScript Object Notation) object.

curl -X POST
"https://<IP of control>/identity-manager/api/v1/auth/token" 
-d "{'name':'<user name>','password':'<user password>'}"
-k

Example:

curl -X POST https://192.168.1.1/identity-manager/api/v2/auth/token -H "Content-Type: application/json" -d "{\"password\": \"boschrexroth\", \"name\": \"boschrexroth\"}" -k

command prompt - get web token

Simple subscription

Send a GET request to "/automation/api/v2/events" for a simple subscription. The response is an SSE (server sent event) stream.

curl -X GET 
"https://<IP of control>/automation/api/v2/events?nodes=<path 1>,<path 2>&publishIntervalMs=1000" 
-H "Authorization: Bearer <token>" 
-k

Example:

Data layer nodes to subscribe to:
- "framework/metrics/system/cpu-utilisation-percent"
- "framework/metrics/system/memavailable-mb"
Subscription interval is 1000ms

curl -X GET "https://192.168.1.1/automation/api/v2/events?nodes=framework/metrics/system/cpu-utilisation-percent,framework/metrics/system/memavailable-mb&publishIntervalMs=1000" -H "Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDE3MDU2MjksImlhdCI6MTcwMTY3NjgyOSwiaWQiOiIxMDAwIiwibmFtZSI6ImJvc2NocmV4cm90aCIsIm5vbmNlIjoiY2I3NjA0NDEtYzQwZC00YWRjLTgwZWMtOTYxYTYyY2FjMGNjIiwicGxjaGFuZGxlIjo4MDg3NjAxNDE1Mzc2NDU4MjAsInJlbW90ZWF1dGgiOiIiLCJzY29wZSI6WyJyZXhyb3RoLWRldmljZS5hbGwucnd4Il19.DlHPoz5V0EeKdAyKqKfWCWcLbtH1hw559bJDj-aCm2wO10MiODynxKx7o8Fr73513EMEPdZh-n1VPU6nftwFa-kNtUBUDsi2NrYVunP02QAndRtUAblsK-MYTHE9Fe3q" -k

command prompt - simple subscription

Generate rule set for complex subscription

A subscription is provided with settings specifying the behavior. These settings are called rule set. Several clients can use the same rule set for their subscription. To generate a rule set for complex subscription send a POST request to "/automation/api/v2/events".

curl -X POST 
"https://<IP of control>/automation/api/v2/events" 
-H "Authorization: Bearer <token>" 
-H "Content-Type: application/json" 
-d "{'properties': {'keepaliveInterval': <time in ms>, 
     'id': '<name of rule set>', 
     'publishInterval': <time in ms>, 
     'errorInterval': <time in ms>}, 
     'nodes': ['<path 1>', '<path 2>']}" 
-k

Example:

Interval availability of data will be checked: keepaliveInterval = 60000ms
Name of rule set: id = subID
Interval the data is published: publishInterval = 1000ms
Time to re-read data if an error was received for a node: errorInterval = 10000ms
Data layer nodes to subscribe to:
- "framework/metrics/system/cpu-utilisation-percent"
- "framework/metrics/system/memavailable-mb"

curl -X POST "https://192.168.1.1/automation/api/v2/events" -H "Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDE3MDc3OTIsImlhdCI6MTcwMTY3ODk5MiwiaWQiOiIxMDAwIiwibmFtZSI6ImJvc2NocmV4cm90aCIsIm5vbmNlIjoiOWZkNGQxMDgtMWM1YS00NGM3LTg4NmYtNmM2NDg5N2Y3NTY2IiwicGxjaGFuZGxlIjoxMTAxNjY2MTU1MTA1NTgxODczMCwicmVtb3RlYXV0aCI6IiIsInNjb3BlIjpbInJleHJvdGgtZGV2aWNlLmFsbC5yd3giXX0.lmMxXInyEPsmEKCXscsuGSOjW_L4eubROf2JjmgSDDbY2F85lX16ZN1EJ7eDIghUb9mhlEjzkzr7b7DEW5-sucZo8yIYBsyjPen_scx_s2sHOL0JOQQgpkmwIOKPWDx5" -H "Content-Type: application/json" -d "{'properties': {'keepaliveInterval': 60000, 'id': 'subID', 'publishInterval': 1000, 'errorInterval': 10000}, 'nodes': ['framework/metrics/system/cpu-utilisation-percent', 'framework/metrics/system/memavailable-mb']}" -k

Complex subscription using rule set

Use a GET request for a subscription using predefined rule set. The response is an SSE (server sent event) stream. Beware that via the web interface created rule sets will automatically be deleted when unused for one minute.

curl -X GET 
https://<IP of control>/automation/api/v2/events/<name of rule set>
-H "Authorization: Bearer <token>" 
-k

Example:

Name of rule set to be used for subscription: subID

curl -X GET https://192.168.1.1/automation/api/v2/events/subID -H "Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDE3MDU2MjksImlhdCI6MTcwMTY3NjgyOSwiaWQiOiIxMDAwIiwibmFtZSI6ImJvc2NocmV4cm90aCIsIm5vbmNlIjoiY2I3NjA0NDEtYzQwZC00YWRjLTgwZWMtOTYxYTYyY2FjMGNjIiwicGxjaGFuZGxlIjo4MDg3NjAxNDE1Mzc2NDU4MjAsInJlbW90ZWF1dGgiOiIiLCJzY29wZSI6WyJyZXhyb3RoLWRldmljZS5hbGwucnd4Il19.DlHPoz5V0EeKdAyKqKfWCWcLbtH1hw559bJDj-aCm2wO10MiODynxKx7o8Fr73513EMEPdZh-n1VPU6nftwFa-kNtUBUDsi2NrYVunP02QAndRtUAblsK-MYTHE9Fe3q" -k

command prompt - complex subscription using rule set

Notes

When using a ctrlX CORE^virtual in port forwarding mode the address will change to https://localhost:PORT/... (port in standard is 8443)
Option "-k" is used to skip the TLS certificate verification.
If verification should be done the corresponding certificate needs to installed on the ctrlX CORE and onto your PC operation system. See "How to make an HTTPS connection with ctrlX OS Web Server" for further information.
Swagger UI cannot handle a SSE stream and so looks like getting stuck after starting a subscription. But it can be used to add subscription rule sets.
Subscriptions can be used with different programming languages and interfaces. See online documentation "Subscription - Language binding"

How to subscribe to nodes of the ctrlX Data Layer using REST commands via CURL