EdgeHub RESTFul APIs - 2.3.0
Changelog
| Version | Author | Update date | Comment |
|---|---|---|---|
| 2.1.0 | Sa.Jing / Yuping.Hung | 2024/02/29 | First Version |
| 2.2.0 | ITsung.Shen | 2024/03/25 | Organize documentation and add descriptions |
| 2.3.0 | Sa.Jing / Yuping.Hung | 2024/04/19 | Add Chapter 8 & Chapter 9 (for EdgeHub v2.3 or above)Modify 7.1, 7.2 api format (for EdgeHub v2.3 or above) |
1. Introduction
EdgeHub provides a RESTFul API interface that allows users to access the following contents
- User's authentication
- Groups
- Machines (objects)
- Parameters
- Parameter's Realtime or Historical data
- Devices(Gateways)
- Tag's data
2. How to use
2.1 Base URL
Each EdgeHub site can access the EdgeHub RESTFul API URL based on the following pattern
-
https://api-hub-deviceon-bi-{namespace name}-{cluster name}.{hostname} -
Example : https://api-hub-deviceon-bi-master-ensaas.edge365.advantech.com/
You can also access the API documentation using the following pattern
https://api-hub-deviceon-bi-{namespace name}-{cluster name}.{hostname}/apidoc- https://api-hub-deviceon-bi-master-ensaas.edge365.advantech.com/apidoc
2.2 Preliminary
Except for the 3.1 Login API, all other API requests must include the following two headers in the request header
-
Authorization
- SSO token of the logged-in user, which can be obtained from the Login API response.
- Example:
- Authorization: Bearer
-
IFPTenant
- Tenant ID, specifying the tenant to access, so that the relevant resources in the tenant can be obtained, which can be obtained from the Login API response.
- Example:
- IFPTenant: VGVuYW50.ZDzj9ydUUDRc55_w
3. Auth APIs
3.1 Login
-
Route
POST /v2/auth/login -
Request
-
Body
{
"username": "string (required)", // SSO user account in email format
"password": "string (required)", // SSO user's password
"setCookie": "bool (optional)" // true or false, optional, setting it to true will write a cookie to the browser
}
-
-
Response
-
Body
{
"latency": "string", // API query latency in milliseconds
"data": {
"tokenType": "string", // Token type, currently only supports Bearer
"accessToken": "string", // API access token, which needs to be included in the Authorization header of all subsequent requests
"expiresIn": "timestamp", // Token expiry date in Unix timestamp format, the token is valid for 1 hour
"refreshToken": "string", // String in Base64 format, use this key to refresh the token
"user": {
"tenants": [ // Login user's tenant information
{
"id": "string", // Tenant ID, required for requesting data-related APIs, needs to be included in the header
"name": "string" // Tenant name
}
]
}
}
}
-
-
Example
Request body:
{
"username": "sa.jing@advantech.com",
"password": "abcdefg",
"setCookie": true // optional, setting it to true will write a cookie to the browser
}
Response:
{
"latency": "81ms",
"data": {
"tokenType": "Bearer",
"accessToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJjb3VudHJ5IjoiVFciLCJjcmVhdGlvblRpbWUiOjE2NjczNjY3NDIsImV4cCI6MTY4ODAyNDMwMywiZmlyc3ROYW1lIjoiU2EiLCJpYXQiOjE2ODgwMjA3MDMsImlkIjoiY2I5MmU2M2YtNWE2ZS0xMWVkLTgyNzYtMGE1ODBhZGY0MGNkIiwiaXNzIjoid2lzZS1wYWFzIiwibGFzdE1vZGlmaWVkVGltZSI6MTY2NzM2ODAxOSwibGFzdE5hbWUiOiJKaW5nIiwicmVmcmVzaFRva2VuIjoiOGI2ODQ4OTctMTY0Ny0xMWVlLTg4YmQtMGE1ODBhZGY0MGRiIiwic3RhdHVzIjoiQWN0aXZlIiwidXNlcm5hbWUiOiJzYS5qaW5nQGFkdmFudGVjaC5jb20uY24ifQ.w9wvAPD56nPpOGJKaNyA-R61Wv6DO7k2kQQ4bKojLiXRyq0YoL4AAxyZ_eL5IxCrRtr6Q1ZdGXCRaO5a8mdJSw", // All subsequent requests need to include this token in the Authorization header
"expiresIn": 1688024303, // Token is valid for 1 hour
"refreshToken": "8b684897-1647-11ee-88bd-0a580adf40db", // Used for refreshing the token
"user": {
"tenants": [
{
"id": "VGVuYW50.Y1-NK3QAXhVOdBTZ",
"name": "Root Tenant"
},
{
"id": "VGVuYW50.ZDet-2iqhavNUEAg", // Required for data-related API requests, needs to be included in the header
"name": "satest"
}
]
}
}
}
3.2 Refresh Token
-
Route
POST /v2/auth/refreshToken -
Request
-
Body
{
token: string (required), //string in Base64 format which is got from refreshToken of Login API
}
-
-
Response
-
Body
{
latency: string, // API query latency in milliseconds
data: {
tokenType: string, // Token type, currently only supports Bearer
accessToken: string, // API access token, which needs to be included in the Authorization header of all subsequent requests
expiresIn: timestamp, // Token expiry date in Unix timestamp format, the token is valid for 1 hour
refreshToken: string, // String in Base64 format, use this key to refresh the token
}
}
-
-
Example
Request body:
{
token: 20df5ce0-165e-11ee-88bd-0a580adf40db
}
Response:
{
latency: 9ms,
data: {
tokenType: Bearer,
accessToken: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJjb3VudHJ5IjoiVFciLCJjcmVhdGlvblRpbWUiOjE2NjczNjY3NDIsImV4cCI6MTY4ODAzNDA1MSwiZmlyc3ROYW1lIjoiU2EiLCJpYXQiOjE2ODgwMzA0NTEsImlkIjoiY2I5MmU2M2YtNWE2ZS0xMWVkLTgyNzYtMGE1ODBhZGY0MGNkIiwiaXNzIjoid2lzZS1wYWFzIiwibGFzdE1vZGlmaWVkVGltZSI6MTY2NzM2ODAxOSwibGFzdE5hbWUiOiJKaW5nIiwicmVmcmVzaFRva2VuIjoiM2RhNmUxZmYtMTY1ZS0xMWVlLTg4YmQtMGE1ODBhZGY0MGRiIiwic3RhdHVzIjoiQWN0aXZlIiwidXNlcm5hbWUiOiJzYS5qaW5nQGFkdmFudGVjaC5jb20uY24ifQ.Jmoooaz01KFPdgJhJYOv763m91JIhFCNkaxZzMmlPg4wHEKRvChu-0IqOcdoUuB0JCvoWqvXGSIdjipFBs8y3A,
expiresIn: 1688034051,
refreshToken: 3da6e1ff-165e-11ee-88bd-0a580adf40db
}
}
3.3 Set my tenant
-
Route
POST /v2/auth/setMyTenant -
Request
-
Body
{
tenantId: string (required), //string of tenant id, get it from login API
}
-
-
Response
Status: 200 OK
-
Example
Request body:
{
tenantId:VGVuYW50.ZCI4Q928Cafk07SD
}
Response:
Status: 200 OK
3.4 Logout
-
Route
POST /v2/auth/logout -
Request
N/A
-
Response
Status: 200 OK
-
Example
Request body:
N/A
Response:
Status: 200 OK
4. Groups APIs
4.1 Get groups
-
Route
GET /v2/groups -
Request
-
Header
Keys Type Description Authorization string SSO token of the logged-in user, Bearer token, can be obtained from the Login API response. IFPTenant string Tenant ID, specifies the tenant to access, can be obtained from the Login API response. -
Body
N/A
-
-
Response
-
Body
{
latency: string, //API query latency in millisecond
data: {
groups: [
{
id: string, // Group ID
_id: number, // Group ID (internal used)
parentId: string, // Parent group ID
_parentId: number, // Parent group ID (internal used)
tenantId: string, // Tenant ID
sourceName: string,// Group name, as a key in DB
owner: string, // Tenant owner's account, in email format
timeZone: string, // Asia/Taipei
timeZoneInfo: {
label: string, //(GMT+08:00) Asia/Taipei
timeZone: string, //Asia/Taipei
utcOffset: int, // 480
},
"depth": int, // Group level
"coordinate": {
longitude: number, // Group longitude
latitude: number, // Group latitude
},
"address": string, // Group address
"address2": string, // Group address
"city": string, // Group city
"postalCode": string, // Group postal code
"createdAt": string, // Group created time
"updatedAt": string, // Group last updated time
"img": string, // Group image
"enable": bool, // Group status
"name": [ // Multi-language of group name
{
lang: string, // en-US,zh-CN,zh-TW,ja-JP
text: string, // group name
}
],
"description": [ // Multi-language of group description
{
lang: en-US,// en-US,zh-CN,zh-TW,ja-JP
text: PM Test, // group description
}
],
"descendants": [
// descendants group object, same structure of this object
],
]
}
]
}
}
-
-
Example
Request:
GET https://api-hub-deviceon-bi-master-ensaas.edge365.advantech.com/v2/groups
Response:
{
latency: 28ms,
data: {
groups: [
{
id: R3JvdXA.MTEyMg,
_id: 1122,
parentId: null,
_parentId: null,
tenantId: VGVuYW50.ZWb-tfKRKUpOavef,
sourceName: PM Test,
owner: tracy.su@advantech.com.tw,
timeZone: Asia/Taipei,
timeZoneInfo: {
label: (GMT+08:00) Asia/Taipei,
timeZone: Asia/Taipei,
utcOffset: 480
},
"depth": 1,
"coordinate": {
longitude: 0.0000000000,
latitude: 0.0000000000
},
"address": null,
"address2": null,
"city": "",
"postalCode": "",
"createdAt": "2023-11-29T09:04:54.089Z",
"updatedAt": "2023-11-29T09:04:54.089Z",
"img": "",
"enable": true,
"name": [
{
lang: en-US,
text: PM Test
},
{
lang: zh-CN,
text: PM Test
},
{
lang: zh-TW,
text: PM Test
},
{
lang: ja-JP,
text: PM Test
}
],
"description": [
{
lang: en-US,
text: PM Test
},
{
lang: zh-CN,
text: PM Test
},
{
lang: zh-TW,
text: PM Test
},
{
lang: ja-JP,
text: PM Test
}
],
"descendants": []
]
}
]
}
}
5. Machines APIs
5.1 Get machines (objects) of a group
-
Route
GET /v2/machines/{groupId} -
Request
-
Query string
Keys Type Required Description groupId string Y Group ID, can be obtained from 4.1 Get groups API isStation boolean N filter by isStation prop showGroupObject boolean N query GroupObject or not,default is true search string N search by machine name searchLang string N search language Valid value:en-US,zh-CN,zh-TW,ja-JP.Default is en-US. skip number N skipped page number limit number N number of records per page sortby string N The property name which resources order by[CREATED_AT,UPDATED_AT,NAME,MACHINE_TYPE,PARAMETER_COUNT].Default is CREATED_AT order string N Sort directions,valid value:ASC,DESC.Default is ASC -
Header
Keys Type Description Authorization string SSO token of the logged-in user, Bearer token, can be obtained from the Login API response. IFPTenant string Tenant ID, specifies the tenant to access, can be obtained from the Login API response. -
Body
N/A
-
-
Response
-
Body
{
latency: string, //API query latency in millisecond
data: {
machines: [
{
id: string, // Machine ID
_id: number, // Machine ID (internal used)
groupId: string, // Group ID
_groupId: number, // Group ID (internal used)
tenantId: string, //Tenant ID
sourceName: string, //Machine en-US name
createdAt: string, // Machine created time
updatedAt: string, // Machine last updated time
machineType: {
parentKey: string,//Machine parent type
key: string, //Machine type
},
"isGroupObject": boolean,//Machine is group object or not,group object is automatically created by the system when creating a group
"tmplTypeId": number, //Machine type id(internal used)
"tmplTypeName": string, //Mahicne type name(internal used)
"img": string, //Machine image
"serialNumber": string, //Machine serial number
"almCodeFile": string, //Machine alarm code file,used for alarm setting
"additionalMsgUrl": string, //Machine additional url,used to navigate to other machine-related links.
"minKeptDays": number, //Machine min data saved days
"otherKeptDays": number,//Machine hour,day data saved days
"name": [ // Multi-language of machine name
{
lang: string, // en-US,zh-CN,zh-TW,ja-JP
text: string // machine name
}
],
"description": [ // Multi-language of machine description
{
lang: string, // en-US,zh-CN,zh-TW,ja-JP
text: string // machine description
}
]
},
...
...
],
"machineCount":3,//the total number after filter and search
}
}
-
-
Example
Request:
GET https://api-hub-deviceon-bi-master-ensaas.edge365.advantech.com/v2/machines/R3JvdXA.MTEyMg?skip=1&limit=5&search=obj&showGroupObject=false
Response:
{
latency: 18ms,
data: {
machines: [
{
id: TWFjaGluZQ.MjkwNTI,
_id: 29052,
groupId: R3JvdXA.MTEyMg,
_groupId: 1122,
tenantId: VGVuYW50.ZWb-tfKRKUpOavef,
sourceName: Obj01,
createdAt: 2023-12-01T02:25:49.294Z,
updatedAt: 2023-12-01T02:25:49.254Z,
machineType: {
parentKey: default,
key: DefaultEquipType
},
"isGroupObject": false,
"tmplTypeId": 0,
"tmplTypeName": "Default",
"img": "",
"serialNumber": "",
"almCodeFile": "",
"additionalMsgUrl": "",
"minKeptDays": 7,
"otherKeptDays": 731,
"name": [
{
lang: en-US,
text: Obj01
},
{
lang: zh-CN,
text: Obj01
},
{
lang: zh-TW,
text: Obj01
},
{
lang: ja-JP,
text: Obj01
}
],
"description": [
{
lang: en-US,
text:
},
{
lang: zh-CN,
text:
},
{
lang: zh-TW,
text:
},
{
lang: ja-JP,
text:
}
]
},
...
...
],
"machineCount":3,
}
}
6. Parameters APIs
6.1 Get parameters of a machine (object)
-
Route
GET /v2/parameters/{machineId} -
Request
-
Query string
Keys Type Required Description machineId string Y Machine (object) ID, can be obtained from 5.1 Get machines API valueTypes string[] N filter by valueTypes, values in [Number,String,Discrete] kinds string[] N filter by kinds, values in [Constant,Calculation,undefined], undefined means primitive search string N search by machine name alarm boolean N whether to query parameters with alarms set.default id false after number N query after cursor before number N query before cursor first number N query first records number last number N query last records number sortby string N The property name which resources order by.[NAME,CREATED_AT,UPDATED_AT,KIND,UNIT,ALM_FLAG,RECORDING_RATE].Default is CREATED_AT order string N Sort directions.Valid value:ASC,DESC.Default is ASC -
Header
Keys Type Description Authorization string SSO token of the logged-in user, Bearer token, can be obtained from the Login API response. IFPTenant string Tenant ID, specifies the tenant to access, can be obtained from the Login API response. -
Body
N/A
-
-
Response
-
Body
{
latency: string, //API query latency in millisecond
data: {
parameters: [
{
id: string, //Parameter ID
_id: string, //Parameter ID (internal used)
machineId: string, //Machine ID
_machineId: number, //Machine ID(internal used)
name: string, //Parameter name
scadaId: string,//the gateway scadaId associated with this primitive parameter
tagId: string,//the gateway tag name associated with this primitive parameter
valueType: string, //[Number,String,Discrete]
kind: string, //[Constant,Calculation,undefined]
defaultValue: string,//only constant and calculation can set parameter default value
decimalPrecision: number, //Parameter decimal precision
unit: string, //Parameter unit
spanHi: number,//Parameter spanHi
spanLo: number,//Parameter spanLo
recordingType: string,//Parameter recording type ,[Current,Cumulative]
recordingRate: number,//Parameter recording rate
maxChangeRatePerMin: number,//Cumulative parameer return the maximum change per minute, while current parameter return the maximum change rate per minute.
recordingGroup: number, //not using it now
dataKeptDays: number,//Parameter raw data saved days
stateTxt: string,//Discrete parameter's state descriptor
negativeMode: boolean,//if support negative mode
almFlag: number,// 0:no set alarm 1:set alarm but not enable 3:set and enable alarm
calcFormula: string,//Calculation parameter's formula (internal format)
calcFreq: number,//calculation rate
calcFormulaDisplay: string, //Calculation parameter's formula
createdAt: string,//Parameter created time
updatedAt: string,//Parameter last updated time
cursor: string,
description: [ // Multi-language of parameter description
{
lang: string , // en-US,zh-CN,zh-TW,ja-JP
text: string // parameter description
}
]
},
...
...
],
"parameterCount":3,//the total number after filter and search
}
}
-
-
Example
Request:
GET https://api-hub-deviceon-bi-master-ensaas.edge365.advantech.com/v2/parameters/TWFjaGluZQ.MjkwNTI?first=5&kinds[]=undefined&kinds[]=Constant&sortby=NAME
Response:
{
latency: 9ms,
data: {
parameters: [
{
id: UGFyYW1ldGVy.MjkwNTImQ29uMDE,
_id: 29052&Con01,
machineId: TWFjaGluZQ.MjkwNTI,
_machineId: 29052,
name: Con01,
scadaId: b97457ef-9f91-4400-8b67-7a66dee94e9e,
tagId: Con01,
valueType: Number,
kind: Constant,
defaultValue: 0,
decimalPrecision: 0,
unit: ,
spanHi: 100,
spanLo: 0,
recordingType: Current,
recordingRate: 0,
maxChangeRatePerMin: 100,
recordingGroup: 0,
dataKeptDays: 7,
stateTxt: ,
negativeMode: false,
almFlag: 0,
calcFormula: ,
calcFreq: 0,
calcFormulaDisplay: ,
createdAt: 2023-12-01T02:26:24.086Z,
updatedAt: 2023-12-01T02:26:23.983Z,
cursor: UGFyYW1ldGVy.MjkwNTImQ29uMDE,
description: [
{
lang: en-US,
text:
},
{
lang: zh-CN,
text:
},
{
lang: zh-TW,
text:
},
{
lang: ja-JP,
text:
}
]
},
...
...
],
"parameterCount":3,
}
}
7. Parameter's data APIs
7.1 Get parameter's original calculated data
GET /v2/parameter/HIS/original/calculatedData
-
Request
-
Response
-
Body
analog data format
{
datapoints: []data array,
fieldList: [
maxvalue,
minvalue,
lastvalue,
avgvalue,
datatime,
quality
]
}
discrete data format
{
datapoints: []data array,
fieldList: [
tagvalue,
cumulativedurations,
occurrencenumber,
isfirstvalue,
quality,
datatime
]
}
-
-
Example
Response:
{
datapoints: [
```json
[ 129590, 126000, 129590, 127795, 1701990000000, 0 ],[ 133190,//max value 129600,//min value, 133190,//last value, 131395,//avg value, 1701993600000,//datatime 0//quality ]
],
fieldList: [
maxvalue,
minvalue,
lastvalue,
avgvalue,
datatime,
quality
]
}
7.2 Get parameter's original raw data
GET /v2/parameter/HIS/original/rawData
-
Request
-
Response
-
Body
{
datapoints: []data array,
fieldList: [
datavalue,
quality,
datatime
]
}
-
-
Example
Response:
{
datapoints: [
```json
[ 129590, 0, 1701993590000 ],[ 129600, 0, 1701993600000 ]
],
fieldList: [
datavalue,
quality,
datatime
]
}
7.3 Get parameter's autoscale data
GET /v2/parameter/HIS/:method/data
method: autoScale or fixedScale
-
Request
-
Header
IFPTenant: TenantId (string)
Authorization : Bearer EIToken (string) -
Parameters
Keys Type Required Describe id string Y parameter id startTime int Y timestamp in milliseconds endTime int Y timestamp in milliseconds dataType string Y only max, min, avg, last maxPoints int Y interval string Y sec, min, hour, day, month, year
-
-
Response
-
Body
{
datapoints: []data array,//[value, quality,dataTime]
interval: int,//time interval in milliseconds
nextData: []data array,//only one next data
previousData: []data array,//only one previous data
}
-
-
Example
Response:
{
datapoints: [
```json
[ 6495111, 0, 1693327200000 ], [ 6495711, 0, 1693327800000 ], ], interval: 600000, nextData: [ 6498171, 0, 1693328400000 ], previousData: [ 6494511, 0, 1693326600000 ]
}
7.4 Get parameter's latest data
GET /v2/parameter/RT/data
-
Request
-
Header
IFPTenant: TenantId (string)
Cookie: include EIToken (string) -
Parameter
Keys Type Required Describe id []string Y parameter id before int N data before this timestamp(second) after int N data after this timestamp(second) includeBefore boolean N data include before timestamp or not includeAfter boolean N data include after timestamp or not
-
-
Response
-
Body
{
data: {
datapoints: [
{
quailty: int,
timestamp: timestamp in milliseconds,
value: float or string (depend on data)
}
]
},
"latency": string
}
-
-
Example
GET http://api-hub-deviceon-bi.edgehub.com/v2/parameter/RT/data?id=UGFyYW1ldGVy.NDA0MyZDYWxDdW0
Response:
{
data: {
datapoints: [
{
quailty: 0,
timestamp: 1708596913001,
value: 292301
}
]
},
"latency": "5.479707ms"
}
7.5 Set parameter's data
POST /v2/parameter/RT/data
-
Request
-
Response
-
Body
{
data: {
message : string
},
"latency": string
}
-
-
Example
POST http://api-hub-deviceon-bi.edgehub.com/v2/parameter/RT/data
Request body:
{
paramValue:[
{
id:UGFyYW1ldGVy.MSZTSU0wMDE,
value: 100,
type: 1,
},{
id:UGFyYW1ldGVy.MSZTSU0wMDI,
value: 101,
type: 3,
}
]
}
Response:
{
data: {
message : OK
},
"latency": "200 ms"
}
7.6 Get parameter's statistic data (discrete data type)
GET /v2/parameter/statistic/discrete/:op
op: only support sum
-
Request
-
Response
-
Body
//statistic from startTime to endTime
{
count: int, // status occuer times
duration: int // status duration in seconds
}
-
-
Example
Response:
{
count: 183,
duration: 1830
}
7.7 Get parameter's statistic data (analog data type)
GET /v2/parameter/statistic/analog/:op
op: support avg and sum
-
Request
-
Response
-
Body
//statistic from startTime to endTime
{
value: float
}
-
-
Example
Response:
{
value: 16190.5
}
8. Device and Device tags APIs
8.1 Get devices
-
Route
GET /v2/gateways -
Request
-
Header
Keys Type Description Authorization string SSO token of the logged-in user, Bearer token, can be obtained from the Login API response. IFPTenant string Tenant ID, specifies the tenant to access, can be obtained from the Login API response. -
Query string
Keys Type Required Description kinds string[] N filter by gateway kinds search string N search by gateway name skip number N skipped page number limit number N number of records per page sortby string N The property name which resources order by[CREATED_AT,UPDATED_AT,NAME,GATEWAY_TYPE].Default is NAME order string N Sort directions.Valid value:ASC,DESC.Default is ASC -
Body
N/A
-
-
Response
-
Body
{
latency: string, //API query latency in millisecond
data: {
gateways: [
{
id: string, //Gateway ID
tenantId: string, //Tenant ID
name: string,//Gateway name
kind: string,//[DcADAM,DcWISE,DcEdgeLink,DcSCADA,DcGeneralPC,DcIfpConnector,WebAccess,EdgeLink,IfsGateway,WoAgent,Prediction,MachineCloud]
scadaId: string,//Gateway scadaId
createdAt: string,//Gateway created time
desc: string,//Gateway description
mode: number,//device mode，0=Construction，1=Operation
img: string,//Gateway image
protocolType: number,//Gateway protocol type 0=undefined, 1=Scada, 2=EdgeLink, 3=NBIoT(Coap), 4=iSensing, 5=SmartWorx, 6=DCIFPConnector for worker use
deviceMac: string,//Gateway mac
credentialKey: string,//mqtt credential
nbiotVhost: string,//Gateway nbiot vhost
hwVersion: string, //Gateway Hardware Version
fwVersion: string, //Gateway Firmware Version
swVersion: string, //Gateway Software Version
updatedAt: string,//Gateway updated time
username: string, //iothub credential username
password: string, //iothub credential password
isSystemTimestamp: boolean,//use platform timestamp or not
currentStatus: {//Gateway current status
time: string, //Gateway last data time
status: boolean,//Gateway is active or not
savedAt: string//Gateway last data time
}
},
...
...
],
"gatewayCount": 5,//the total number after filter and search
}
}
-
-
Example
Request:
GET https://api-hub-deviceon-bi-master-ensaas.edge365.advantech.com/v2/gateways?kinds[]=DcSCADA&kinds[]=DcADAM&skip=1&limit=5&sortby=CREATED_AT&order=DESC&search=1
Response:
{
latency: 9ms,
data: {
gateways: [
{
id: R2F0ZXdheQ.Mzc3,
tenantId: VGVuYW50.ZgUPdqt9N0ZgllYt,
name: 1_01,
kind: DcSCADA,
scadaId: 2c016450-f7a4-11ee-93bd-979b2351cfa4,
createdAt: 2024-04-11T01:38:26.285Z,
desc: ,
mode: 1,
img: ,
protocolType: 1,
deviceMac: ,
credentialKey: d40b067f74f6ed29118c3a10917137gz,
nbiotVhost: null,
hwVersion: ,
fwVersion: ,
swVersion: ,
updatedAt: 2024-04-11T01:38:26.285Z,
username: null,
password: null,
isSystemTimestamp: false,
currentStatus: {
time: 2024-04-11T07:29:39Z,
status: false,
savedAt: 2024-04-11T07:29:39Z
}
},
...
...
],
"gatewayCount": 5
}
}
8.2 Get device by device ID
-
Route
GET /v2/gateways/{scadaId} -
Request
-
Query string
Keys Type Required Description scadaId string Y Gateway scadaId, can be obtained from 8.1 Get devices api -
Header
Keys Type Description Authorization string SSO token of the logged-in user, Bearer token, can be obtained from the Login API response. IFPTenant string Tenant ID, specifies the tenant to access, can be obtained from the Login API response. -
Body
N/A
-
-
Response
-
Body
{
latency: string, //API query latency in millisecond
data: {
gateway: {
id: string, //Gateway ID
tenantId: string, //Tenant ID
name: string,//Gateway name
kind: string,//[DcADAM,DcWISE,DcEdgeLink,DcSCADA,DcGeneralPC,DcIfpConnector,WebAccess,EdgeLink,IfsGateway,WoAgent,Prediction,MachineCloud]
scadaId: string,//Gateway scadaId
createdAt: string,//Gateway created time
desc: string,//Gateway description
mode: number,//device mode，0=Construction，1=Operation
img: string,//Gateway image
protocolType: number,//Gateway protocol type 0=undefined, 1=Scada, 2=EdgeLink, 3=NBIoT(Coap), 4=iSensing, 5=SmartWorx, 6=DCIFPConnector for worker use
deviceMac: string,//Gateway mac
credentialKey: string,//mqtt credential
nbiotVhost: string,//Gateway nbiot vhost
hwVersion: string, //Gateway Hardware Version
fwVersion: string, //Gateway Firmware Version
swVersion: string, //Gateway Software Version
updatedAt: string,//Gateway updated time
username: string, //iothub credential username
password: string, //iothub credential password
isSystemTimestamp: boolean,//use platform timestamp or not
currentStatus: {//Gateway current status
time: string, //Gateway last data time
status: boolean,//Gateway is active or not
savedAt: string//Gateway last data time
}
}
}
}
-
-
Example
Request:
GET https://api-hub-deviceon-bi-master-ensaas.edge365.advantech.com/v2/gateways/4360cf10-f618-11ee-b196-fb447c5772f3
Response:
{
latency: 9ms,
data: {
gateway: {
id: R2F0ZXdheQ.MzUz,
tenantId: VGVuYW50.ZgUPdqt9N0ZgllYt,
name: test-device-record-data,
kind: DcSCADA,
scadaId: 4360cf10-f618-11ee-b196-fb447c5772f3,
createdAt: 2024-04-09T02:24:31.374Z,
desc: ,
mode: 1,
img: ,
protocolType: 1,
deviceMac: ,
credentialKey: 9f7c06dee2b1423cbcd1bf47764db6w6,
nbiotVhost: null,
hwVersion: ,
fwVersion: ,
swVersion: ,
updatedAt: 2024-04-09T02:24:31.374Z,
username: null,
password: null,
isSystemTimestamp: false,
currentStatus: {
time: 2024-04-11T07:29:39Z,
status: false,
savedAt: 2024-04-11T07:29:39Z
},
}
}
}
8.3 Get tags by device
-
Route
GET /v2/tags/{gatewayId} -
Request
-
Query string
Keys Type Required Description gatewayId string Y Gateway ID, can be obtained from 8.1 Get devices api searchTagId string N search by tagId valueTypes string[] N filter by tag value types, value in [UnKnow,Number,String,Discrete] tagIds string[] N query by multi tagIds includeBlocks boolean N include Blocks or not,default is true block string N search by block name skip number N skipped page number limit number N number of records per page -
Header
Keys Type Description Authorization string SSO token of the logged-in user, Bearer token, can be obtained from the Login API response. IFPTenant string Tenant ID, specifies the tenant to access, can be obtained from the Login API response. -
Body
N/A
-
-
Response
-
Body
{
latency: string, //API query latency in millisecond
data: {
tags: [
{
id: string,//Tag ID Base64(Tag).Base64(GatewayID:TagName)
tagId: string,//Tag name
valueType: string, //[UnKnow,Number,String,Discrete]
connectionStatus: {
status: boolean,//Tag connection status
ts: string //Tag updateTime
},
"createdAt": string,//Tag updateTime
"updatedAt": string,//Tag updateTime
"dcUpdateTime": string,//Tag updateTime
"dcDataTime": string,// Tag data
"dcDataValue": number,//Tag value
"dcQuality": number,//Tag quality number
"dcIsNum": boolean,//Tag is number or not
"dcBlockType": string,//Tag block type
"dcSpanHi": number,//Tag spanHi
"dcSpanLo": number,//Tag spanLo
"dcDecimalPrecision": number,//Tag Decimal Precision
"dcStateTxt": string,//Discrete parameter's state descriptor
"dcDesc": [],// Tag desription
"dcRecordData": boolean// Tag record data or not
},
...
...
],
"tagCount": 5,//the total number after filter and search
}
}
-
-
Example
Request:
GET https://api-hub-deviceon-bi-master-ensaas.edge365.advantech.com/v2/tags/R2F0ZXdheQ.MzUz?searchTagId=tag&valueTypes[]=Number&skip=1&limit=5&includeBlocks=true
Response:
{
latency: 9ms,
data: {
tags: [{
id: VGFn.MzUzOiNNU1lTX0VkZ2VTdGF0dXM,
tagId: #MSYS_EdgeStatus,
valueType: Discrete,
isAcquiring: false,
saveToHistory: false,
connectionStatus: {
status: true,
ts: 2024-04-18T06:19:46Z
},
"createdAt": "2024-04-18T06:19:46Z",
"updatedAt": "2024-04-18T06:19:46Z",
"dcUpdateTime": "2024-04-18T06:19:46Z",
"dcDataTime": "2024-04-18T06:19:46Z",
"dcDataValue": 0,
"dcQuality": 0,
"dcIsNum": true,
"dcBlockType": "",
"dcSpanHi": 1,
"dcSpanLo": 0,
"dcDecimalPrecision": 0,
"dcStateTxt": "",
"dcDesc": [],
"dcRecordData": true
},
...
...
],
"tagCount": 101
}
}
9. Device tags' data APIs
9.1 Get tag's original calculated data
GET /v2/device/HIS/original/calculatedData
-
Request
-
Response
-
Body
analog data format
{
datapoints: []data array,
fieldList: [
maxvalue,
minvalue,
lastvalue,
avgvalue,
datatime,
quality
]
}
discrete data format
{
datapoints: []data array,
fieldList: [
tagvalue,
cumulativedurations,
occurrencenumber,
isfirstvalue,
quality,
datatime
]
}
-
-
Example
Response:
{
datapoints: [
```json
[ 129590, 126000, 129590, 127795, 1701990000000, 0 ],[ 133190,//max value 129600,//min value, 133190,//last value, 131395,//avg value, 1701993600000,//datatime 0//quality ]
],
fieldList: [
maxvalue,
minvalue,
lastvalue,
avgvalue,
datatime,
quality
]
}
9.2 Get tag's original raw data
GET /v2/device/HIS/original/rawData
-
Request
-
Response
-
Body
{
datapoints: []data array,
fieldList: [
datavalue,
quality,
datatime
]
}
-
-
Example
Response:
{
datapoints: [
```json
[ 129590, 0, 1701993590000 ],[ 129600, 0, 1701993600000 ]
],
fieldList: [
datavalue,
quality,
datatime
]
}
9.3 Get tag's autoscale data
GET /v2/device/HIS/:method/data
method: autoScale or fixedScale
-
Request
-
Header
IFPTenant: TenantId (string)
Authorization : Bearer EIToken (string) -
Parameters
Keys Type Required Describe id string Y tag id startTime int Y timestamp in milliseconds endTime int Y timestamp in milliseconds dataType string Y only max, min, avg, last maxPoints int Y interval string Y sec, min, hour, day, month, year
-
-
Response
-
Body
{
datapoints: []data array,//[value, quality,dataTime]
interval: int,//time interval in milliseconds
nextData: []data array,//only one next data
previousData: []data array,//only one previous data
}
-
-
Example
Response:
{
datapoints: [
```json
[ 6495111, 0, 1693327200000 ], [ 6495711, 0, 1693327800000 ], ], interval: 600000, nextData: [ 6498171, 0, 1693328400000 ], previousData: [ 6494511, 0, 1693326600000 ]
}
9.4 Get tag's latest data
GET /v2/device/RT/data
-
Request
-
Response
-
Body
{
data: {
datapoints: [
{
quailty: int,
timestamp: timestamp in milliseconds,
value: float or string (depend on data)
}
]
},
"latency": string
}
-
-
Example
GET http://api-hub-deviceon-bi.edgehub.com/v2/device/RT/data?id=VGFn.MTIzNDphYmM
Response:
{
data: {
datapoints: [
{
quailty: 0,
timestamp: 1708596913001,
value: 292301
}
]
},
"latency": "5.479707ms"
}
9.5 Set tag's data
POST /v2/device/RT/data
-
Request
-
Response
-
Body
{
data: {
message : string
},
"latency": string
}
-
-
Example
POST http://api-hub-deviceon-bi.edgehub.com/v2/device/RT/data
Request body:
{
tagValue:[
{
id:VGFn.MTIzNDphYmM,
value: 100,
},{
id:VGFn.MTIzNDplZmc,
value: 101,
}
]
}
Response:
{
data: {
message : OK
},
"latency": "200 ms"
}
9.6 Get tag's statistic data (discrete data type)
GET /v2/device/statistic/discrete/:op
op: only support sum
-
Request
-
Response
-
Body
//statistic from startTime to endTime
{
count: int, // status occuer times
duration: int // status duration in seconds
}
-
-
Example
Response:
{
count: 183,
duration: 1830
}
9.7 Get tag's statistic data (analog data type)
GET /v2/device/statistic/analog/:op
op: support avg and sum