WAGO Cloud - REST-API Documentation
[Pages:41]WAGO Cloud - REST-API Documentation
WAGO Cloud - REST-API Documentation
Vers ion: 2. 1 2022-10-27 File name: WAGO Cloud - RE ST-API D ocumentation.docx
WAGO Cloud - REST-API Documentation
Table of contents
1 Overvi ew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Supported Components by REST -API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2 D ef init ion of Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3 S upported Operations by RES T-AP I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 RES T-API Usage via S wagger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2 RES T-AP I K ey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2. 1 Create an AP I Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.3 A ut horization via S wagger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.4 RES T-AP I Op eratio ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4 RES T-API S cenarios vi a HTTP requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.1 A ut horization via RES T-AP I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.2 Get S ubscription and Workspac e Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.3 Creat e a D evice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.4 Get all Commands Support ed f or a Devic e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.5 S end a Command to the Dev ice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.6 Get the Wo rkspace St ruct ure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 4.7 Get Telemet ry Dat a. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5 Publi c E vent Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.1 S upported Public Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2 S ubscrib e for a Public Event - POS T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 5.3 S equenc e of Events: Sync hrono us Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.4 List all Public Event Subsc riptions - GE T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 5.5 Unsubscribe f rom a P ublic Event - DELE TE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.6 Receiv e Scheduled CSV Export Ev ents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.7 Receiv e Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.8 Receiv e Devic e St ate Ev ents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 5.9 Receiv e Telemetry D ata Ev ents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6 Asynchronous Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 6.1 How to use it . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 6.2 D evice Command Response St ates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 6.3 Change Timeout Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 6.4 Retry P att ern f or WA GO Cloud Devic e Command S erv ice . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7 Query the tag inform ation for mul tipl e devi ces via a batch api . . . . . . . . . . . . . . . . . . . 40 7.1 General: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 7.2 Request body: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 7.3 Responses: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 7.4 Additio nal Not es: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
WAGO Cloud - REST-API Documentation
1 Overview
B es ides managing t he d evices in t he WA GO Cloud Web -Portal, it is also possible t o manage t he WA GO Cloud and t he data v ia t he REST-API. The RE ST-API p rovides t he f ollowing use c ases and f unctions:
Us e c as es of t he RE ST-API: ? S c ripting e. g . automatic d evice reg istration ? Cus t om applications ? Data access on his t orical data
RE S T-A PI Functions: ? D ev ice management and ac c ess to d evice d ata ? Sub scription and wo rk space management ? A larm conf iguration and ac c ess to alarm d ata
This d ocument d escribes t he architecture f rom t he new v ersion of t he RE ST-API and g iv es s ome b asic example how t o register a d evice and receive d ata f rom t he d evice. If y o u are wo rking with an o lder v ersion of t he RE ST A PI v 1 (deprecated) o r v 2 (d ep recated), p lease us e t he REST-API d ocumentation f rom 2018 -10-01, V ersion 2.2.
WAGO Cloud - REST-API Documentation
2 Supported Components by REST-API
2.1 Overview
The f ollowing picture s hows t he components, which are s upported by t he REST -API. E ac h t erm used in t he picture is d escribed in t he t able f ollowed by t he picture.
Frame/Core
? Subscription info ? Workspace info ? Workspace/folder/device
structure management ? Event management
Devices ? Device management ? Command management ? Collection info ? Tag info
Alarms ? Manage alarm configurations ? Manage triggered alarms ? Alarm status
Telemetry Data ? Get raw data ? Get aggregated data
Term Fram e/Core
Device
Figure 1: Supported components
2.2 Definition of Terms
Defi n itio n
The g eneral f unctionality in t he WA GO Cloud is c lustered in t he f rame/core c omponent, e.g. s ubscription and wo rk space management.
The RE S T-API allows t o get s ubscription and workspace inf ormation. The management of t he workspace s tructure is als o possible. It is also possible t o c reate a s ub scription t hat inf orms about an event by s ending c allbacks t o a s pecif ied c lient .
D ev ices c an b e c reated in t he WAGO Cloud. D evices, t o gether with f olders, are contained in t he wo rkspace s t ructure. D ata c an b e s ent f rom t he p hysical d evice. The s ent d ata us e c ollections and t ags f or t he t ransmission of d ev ice d ata. Commands c an b e ex ecuted o n t he device.
The RE S T-API allows t o get d evice inf o and c reate o r d elete devices. Commands c an b e read and t riggered on t he d evice. Co llections and t ags c an be also c reated, up d ated and d eleted. Conf iguration of d evice is also p o ssible. D eveloper c an use A PI t o conf igure d evice ins t ead of s ending a t ag conf iguration message.
WAGO Cloud - REST-API Documentation
Term Tel emetry data
Alarms
Defi n itio n
The p hysical device c an s end t elemetr y data to t he c loud. The t elemetry data c an be v isualized in t he WAGO Cloud, e. g . in a d ashboard o r in a t rend.
The RE S T-API allows t o export t he raw d ata f rom t he d ev ice and t he aggregat ed data f rom t he device. You c an us e t he d ata in any other 3r d p arty t ool.
The WA GO Cloud c ontains an alarm management app. A larm conf iguration c an be c reated with s everal alarm rules . While s ending t elemet ry d at a f rom devices, t he alarm c onf igurations will b e c hecked and if a rule is met an alarm in t he WA GO Cloud will b e c reated.
The RE S T-API s upports t he management of t he alarm c o nf igurations and t he management of t riggered alarms.
The ac c ess t o t he WA GO Cloud c omponents is always res tricted b y t he WAGO Cloud us er management. A n A PI k ey (p rimary o r s econdary) is necessary A ccess t o WAGO Clo ud is always v ia a us er.
2.3 Supported Operations by
REST -API
App / Category Method / Operation
Descri ption
Core 1.0 -
GET
S ubscriptions / ap i/core/subscriptions
Get s all s ubscription inf ormation t he us er does hav e ac cess t o.
GET / ap i/core/subscriptions/{id}
Get s t he s ubscription inf ormation f or t he s p ecified id.
GET / ap i/core/subscriptions/{id} / wo rkspaces
Gets a list of all wo rk spaces f or t he s ub scription with t he given id.
PUT / ap i/core/subscriptions/{id}/ apps
Reg ister or updat e t he reg istration of an ex isting ap p lication.
GET / ap i/core/subscriptions/{id}/ apps
Gets the list of all reg istered apps t hat were reg istered f or t he s ub scription with t he given
id.
D ELETE / ap i/core/subscriptions/{id}/ apps /{name}
D eregist ers t he app with the g iven name from the
WAGO Cloud - REST-API Documentation
App / Category Method / Operation
Core 1.0 W o r k s p ac es
GET / ap i/core/workspaces/{id}/structure
POST / ap i/core/workspaces/{id}/structure PUT / ap i/core/workspaces/{id}/structure GET / ap i/core/workspaces/{id}/structure / s earch
GET / ap i/core/workspaces/{id}/structure / {no deId}
GET / ap i/core/workspaces/{id}/structure / {no deId}/additional -properties
PUT / ap i/core/workspaces/{id}/structure / {no deId}/additional -properties
GET / ap i/core/workspaces/{id}/strcture / {no deId}/aggregated-tags
D ELETE / ap i/core/workspaces/{f olderId} / f older D ELETE / ap i/core/workspaces/{id}/structure / {no deId}/additional -properties / {p ropertyName}
GET / ap i/core/workspaces/{id}/featurep ermissions
Descri ption
s ub scription with t he given id.
Get s t he wo rkspace structure for the wo rk space wit h t he given id.
Creat es a f older in t he wo rk space s tructure.
Up d ates a node in t he wo rk space s tructure.
S earc hes f or o bjects (d ev ices/folder) wit hin t he wo rk space wit h t he given id.
S earc hes f or t he s tructure no d e wit h t he g iven node id in t he wo rkspace with t he g iven wo rkspace id.
Get s t he addit ional p ro perties f or a s p ecif ic no d e f older o r d evice, c o llection o r t ag.
Creat es o r updates t he ad d itional properties f or a s p ecific node f older o r d ev ice, c ollection o r t ag.
Get s t he c onfigured s t ructural t ag aggregates f o r a f older, d evice o r wo rk space
D eletes t he s pecif ied f o lder and its s ub-f olders.
D eletes the additional p ro perties f or a s p ecif ic no d e f older o r d evice, c o llection o r t ag with t he g iv en p roperty name.
Get s t he f eature p ermissions t he c alling us er d oes have within the
WAGO Cloud - REST-API Documentation
App / Category Method / Operation
Core 1.0 Events
POST / ap i/core/eventsubscriptions
GET / ap i/core/eventsubscriptions
D ELETE / ap i/core/eventsubscriptions/ {id}
Device 1.0 ? Devices
P OS T/ api/deviceapp/batch
GET / ap i/deviceapp/devices
POST / ap i/deviceapp/devices
GET / ap i/deviceapp/devices/{id} PUT / ap i/deviceapp/devices/{id}
D ELETE / ap i/deviceapp/devices/{id} GET / ap i/deviceapp/devices/{id} / c o mmands POST / ap i/deviceapp/devices/{id} / c o mmands/{command}
GET / ap i/deviceapp/devices/{deviceId} / c o mmandResponse / {c ommandResponseId}
Descri ption
wo rk space wit h t he given id entif ier.
Creat es a s ubscript ion t hat inf orms about an ev ent by s ending c allbacks t o a s pecif ied c l i ent.
Lis t s all c urrently ac tive ev ent s ubscriptions.
D eletes a p reviously c reat ed ev ent s ub scription.
E x ecute batch requests related to the Devices. It s up port multiple A PI req uests s et in t he body and req uest c an d epends o n o t hers in t he b atch list.
Get s all d evices f or t he g iv en workspace t he user d o es have ac cess t o.
Creates a d evice in the wo rk space wit h t he given id.
Returns the d evice with the g iven id.
Up d ates p roperties of a d ev ice with t he g iven id.
D eletes t he d evice with g iv en id.
Get s all c ommands s up ported b y t he d evice with the g iven id.
S end s t he specified c o mmand request t o t he d ev ice with t he g iven id.
Get s t he s pecif ied c o mmand response as y nchronously with t he g iv en c ommand response id
WAGO Cloud - REST-API Documentation
App / Category Method / Operation
POST / ap i/deviceapp/devices/{deviceId} / c o mmandsAsync/{command}
Device 2.0 ? Devices
GET / ap i/deviceapp/devices/{id} / c o llections
PUT / ap i/deviceapp/devices/{id} / c o llections
GET / ap i/deviceapp/devices/{id} / c o llections/{key}/t ags
PUT / ap i/deviceapp/devices/{id} / c o llections/{key}/t ags
P OS T/ api/deviceapp/devices/{id} / c o mmands/{command}
GE T/ api/deviceapp/devices / {d eviceId}/commandResponse / {c ommandResponseId}
P OS T/ api/deviceapp/devices / {d eviceId}/commandsAsync / {c ommand}
Tel emetry 1.0 Tel emetry Data
POST / ap i/telemetry/telemetrydata/raw
POST / ap i/telemetry/telemetrydata / ag gregates/datapoints
POST / ap i/telemetry/telemetrydata / ag gregates/timeinterval
Descri ption
S end s t he specified c o mmand request as y nchronously to t he d ev ice with t he g iven p arameters.
Get s all c ollections f or t he d ev ice with t he g iven id.
Creat es/Updates t he c o llections f or t he d evice with the g iven id.
Gets the tags for the s p ecified c ollection f or t he d ev ice with t he g iven id.
Creat es/Updates t he t ags f o r t he device collection.
S end s t he specified c o mmand request t o t he d ev ice with t he g iven id.
Get s t he s pecif ied c o mmand response as y nchronousl y with t he g iv en c ommand response id
S end s t he specified c o mmand request as y nchronously to t he d ev ice with t he g iven p arameters.
Get s t he raw d ata v alues f o r all g iven t ag d es criptions.
Get s t he aggregated d ata v alues f or t he given t ag d es criptions. The res ult will b e p acked into t he g iv en number of ev en s ized d atapoints.
Get s t he aggregated d ata v alues f or t he given t ag d es criptions. The res ult
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.