API FAQs¶
How to get Organization ID (orgId
) ¶
In the left navigation bar of the EnOS Console, click IAM > Organization Profile . The Organization ID is the orgld
.
How to get model ID (modelId
) ¶
In the left navigation bar of the EnOS Console, click Asset Tree, select the target asset tree, and search for the device name you want to query.
Select the device and click View after the model name in the summary information on the right. The model identifier is
modelId
.
How to get Asset ID (assetId
) ¶
In the left navigation bar of the EnOS Console, click Asset Tree, select the target asset tree, and search for the device name you want to query.
Click the device and the Asset ID in the Basic Information is
assetId
.
How to get the measuremet point (pointId
) ¶
In the left navigation bar of the EnOS Console, click Asset Tree, select the target asset tree, and search for the device name you want to query.
Click on the device and the identifier in the Measurement Points is
pointId
.
How to get Access Key (accessKey
) ¶
accessKey
is the service account that EnOS assigns to the application for authentication purpose. accessKey
can be gotten by application registration. To get the information, perform the following steps:
Click Application Registration in the left navigation bar of the EnOS Console.
Select the application that needs to invoke the API and view the Access Key in the basic information.
How to get User ID (userId
)¶
Click the user profile icon in the upper right corner of EnOS Console.
In the pop-up window, find the User ID of the current user, for example,
u15426865866571
.
How does projection
crop the result set?¶
The projection
parameter is used to crop the data
result set, and its data type is String Array
. Each of these strings represents a result field that needs to be returned in the returned result. Any fields that are not specified in the projection
would not be returned in the result set. When specifying a field, you can use:
Symbol |
Description |
|
Stand for each object in an array |
|
Stand for any field value |
|
Stand for sub-field |
Taking the following result set for example:
[ {
"modelId": "planet",
"assetId": "TZ8AOlJU",
"timezone": "+00:00",
"name": {
"i18nValue": {
"en_US": "English name ",
"zh_CN": "Chinese name"
},
"defaultValue": "venus!"
},
"attributes": {
"system": "Solar System"
},
"modelIdPath": "/planet",
"orgId": "yourOrgId",
"desc": null,
"tags": {}
},
{
"modelId": "planet",
"assetId": "CZ20AFJX",
"timezone": "+00:00",
"name": {
"i18nValue": {
"en_US": "English name ",
"zh_CN": "Chinese name"
},
"defaultValue": "mars!"
},
"attributes": {
"system": "Solar System"
},
"modelIdPath": "/planet",
"orgId": "yourOrgId",
"desc": null,
"tags": {}
}]
When you only wants to get the defaultValue
fields of modelId
, assetId
and name
, you can use such cropping parameters:
"projection": [ "[*].modelId", "[*].assetId","[*].name.defaultValue"]
The returned result set after cropping is given as follows:
[{
"modelId": "planet",
"assetId": "TZ8AOlJU",
"name": {
"defaultValue": "venus!"
}
},
{
"modelId": "planet",
"assetId": "CZ20AFJX",
"name": {
"defaultValue": "mars!"
}
}]
How to use expression¶
Note
All supported expression syntaxes are listed here. Each API can support different fields and syntaxes in the query expression. Please follow the instructions of each API request parameter.
The API interface supports to specify the query criteria in the way of SQL-like conditional statements. This type of statements is called a query expression. The query expression supports the following syntax:
Query Criterion |
Expression Sample |
Description |
---|---|---|
Determine whether a key is existed in a tag, filtering the tags with this specified key |
|
There is a key of “k1” in the tags, which matches the tag whose tag key is “k1”. The tag value is not considered. |
Determine whether a key is NOT existed in a tag, filtering the tags without this specified key |
|
The key of “k2” does not exist in the tags. It matches the tag whose tag key is NOT “k2”. The tag value is not considered. |
Determine whether a field is equal to a value |
|
The value of the |
Determine whether the value of a field is one of a set of values |
|
The value of the |
Determine whether a field is not equal to a value |
|
The value of the |
Determine whether an internationalized name field is fuzzy matching with a value |
|
The value of the |
|
The value of the name field is fuzzy matching with “capacity” under en_US locale. |
|
If the |
|
The value of the |
If the |
|
The value of the |
Internationalized name representation¶
In the request parameters and return results, the internationalized name structure is used to represent internationalized names.
Internationalized name struct¶
Name |
Data Type |
Description |
defaultValue |
String |
Default name |
i18nValue |
Map(Key is of String type and the Value is of String type) |
Name under each Locale. The key is locale, and the value is the name under each locale. |
defaultValue
refers to the name that should be used when the locale
used is not specified in i18nValue
. The locale
format follows the Unicode locale identifier, such as “en_US”. For more information, see https://www.unicode.org/reports/tr35/tr35-55/tr35.html#BCP_47_Language_Tag_Conversion.
Currently internationalized names only support zh_CN and en_US.
Sample:
{
"defaultValue": "Turbine",
"i18nValue": {"zh_CN": "Turbine", "en_US": "Turbine"}
}
The above-mentioned sample shows that, when the used locale
is “zh_CN”, the name is “Turbine”; when the used locale
is “en_US”, the name is “Turbine”; when any other locale
is used, the name is “Turbine”.
Timezone representation¶
There are tow timezone representation methods available.
Time offset relative to UTC, such as “+08:00” or “-05:00”. When this representation method is used, the summer time is not supported.
Follow the IANA TZ name, such as “America / Los_Angeles”. For more information, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
Timestamps used in API¶
It refers to the timestamp in the result returned by the API. It is the Unix timestamp of the UTC time zone, represented in milliseconds.
Time parameters used in API¶
In the API request parameters, the time is specified in a string format, where local time and UTC time parameter formats are supported. The localtime is a date/time string, and the UTC time uses ISO8601 standard format. When the user invokes an interface, the EnOS service will automatically determine whether it is localtime or UTC time according to the agreed time format without the need to pass the time zone information.
Date and time format adopted by localtime¶
Data Type |
Example Value |
Description |
String<br>YYYY-MM-DD HH:mm:ss |
2019-04-17 10:30:00 |
|
String<br>YYYY-MM-DD HH:mm:ss.SSS |
2019-04-17 10:30:00.000 |
Only when it is supported by API |
The EnOS service will convert the time information according to the time zone information configured on the asset being queried. For example, if the asset timezone is UTC+0800, then 2019-04-17 10:30:00 = 2019-04-17T10:30:00+0800 = UNIX timestamp 1555468200.
Taking into account the summer time, the invoker will judge and process it according to the timestamp in the response result set.
The platform requires additional performance overhead for timezone conversion. Especially for request queries for large amounts of data, there may be longer response time, and some interfaces would be appropriately limited, depending on performance bottlenecks.
ISO8601 standard time format adopted by UTC time¶
Data Type |
Example Value |
String<br>YYYY-MM-DD’T’HH:MM:ss’Z’ |
2019-04-17T02:30:00Z |
When the request format is UTC, the EnOS service will query as per UTC without time zone, i.e. 2019-04-17T02:30:00Z= UNIX timestamp 1555468200000.
How to use tag¶
The EnOS service supports to use tags to manage objects, and can search for objects based on tags. The tags use the Map struct (Key is of String type and the Value is of String type).
Item |
Descripton |
---|---|
Key |
|
Value |
|
When updating the tags, they must be updated as a whole part. For example, a tag “abc:123” is already existed. To add a new tag “bcd:234”, these 2 tags need to be passed together: {abc:123, bcd:234}.
What is model path and how to use it¶
The thing models can have inheritance relationship with each other. For example, the “dual-feed turbine” thing model inherits from the “turbine” thing model. The model path is used in the API request parameters and return results to represent the inheritance relationship among models.
The data type of the model path is String. The model path starts with the “/” character and connect the individual model Ids on the inherited path with the “/” character.
For example, the thing model model_x
inherits from model_y
, and the model_y
inherits from root_model_z
.
Then, the model path for model_x
is: “/root_model_z/model_y/model_x”
The model path for root_model_z
is: “/root_model_z”.
attributes
representation¶
There is a group of static attributes on the asset or device. In the API request parameters or return results, the static attribute group is represented as Map (Key is of String and the Value is of String, Integer, Number, Array or Object type). Where, the key is the attribute Id defined in the thing model, and the value is the value of attribute. The type of value is defined by the thing model.
How to specify a device¶
There are two ways to specify a device asset in the API:
By using
assetId
By using
productKey
anddeviceKey
In the request parameters of the API, three parameters are generally provided for the user to specify a device asset. All three parameters are optional, but the user must choose one from then to specify the device:
Specify
assetId
Specify both
productKey
anddeviceKey
Name |
Data Type |
Required or Not |
Description |
assetId |
String |
false |
Asset ID |
productKey |
String |
false |
Product key |
deviceKey |
String |
false |
Device key |
How to get the ID of an asset tree¶
Each asset tree has a Tree ID. Users can view the ID of each asset tree in the Asset Tree page under Device and Asset in the console. Users can also get all asset trees under the OU through the Search Asset Tree interface. For details about asset trees, see Asset Trees。
How to use dataDefinition ¶
dataDefinition
is the data definition of the datatype
in the structure. For example, when the datatype
is “STRING”, dataDefinition
defines the string length; when the datatype
is “ENUM”, dataDefinition
defines the value and description.
ENUM¶
When the datatype
is ENUM
, an enumDesc
struct is defined in dataDefinition
. The key in enumDesc
is the valid value of the enumeration, and the value is the internationalized description of the valid value. The data type of enumType
is enumeration, only “INT” and “STRING” are allowed.
Sample
{
"enumDesc": {
"1": {
"defaultValue": "one",
"i18nValue": {
"en_US": "one",
"zh_CN": "一"
}
},
"2": {
"defaultValue": "two",
"i18nValue": {
"en_US": "two",
"zh_CN": "二"
}
}
},
"enumType": "INT",
"defaultValue":1
}
BOOL¶
When the datatype
is BOOL
, a boolDesc
structure is defined in dataDefinition
. The values of “true” and “false” describe the meanings of “true” and “false”.
Sample
{
"boolDesc":{
"true": "enabled",
"false": "disabled"
},
"defaultValue":true
}
STRING¶
When the datatype
is STRING
, a maxLength
is defined in dataDefinition
to specify the maximum length of the string. The maximum length of the string is 1024 bits.
Sample
{
"maxLength": 1024
}
STRUCT¶
When the datatype
is STRUCT
, dataDefinition
defines each member in the struct
as items
.
items
are separated by braces ({}) and defined with identifier
, name
, dataType
, dataDefinition
, unit
, and required
.
The dataType
of the items
can be any type other than struct
.
Sample
{
"items":[
{
"identifier": "delta",
"name": {
"defaultValue": "delta",
"i18nValue": {
"en_US": "delta"
}
},
"dataType": "INT",
"dataDefinition":{
},
"unit": "rpm",
"required":true
}
]
}
ARRAY¶
When the dataType
is ARRAY
, dataDefinition
defines the data type of the array element with itemType
.
itemType
can only be “INT”, “FLOAT”, “DOUBLE”, or “STRING”.
Sample
{
"itemType":"INT"
}
Others¶
When the dataType
is INT/FLOAT/DOUBLE/TIMESTAMP/DATA/FILE, dataDefinition
is “null”.