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