10/23/2024

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

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 Layer -> Subscriptions

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 COREvirtual 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"

Related Links

2

Latest published/updated articles

Types
How-to
Categories
Controls