API FAQs¶
如何获取组织ID（orgId）信息
在EnOS Console左边导航栏中点击 身份与授权 > 组织信息。组织ID即为 orgId。
如何获取模型标识符（modelId）信息
在EnOS Console左边导航栏中点击 资产树，选择目标资产树，搜索想要查询的设备名称。
选择设备，点击右侧概要信息中模型名称后的 查看，模型标识符即为
modelId。
如何获取Asset ID（assetId）信息
在EnOS Console左边导航栏中点击 资产树，选择目标资产树，搜索想要查询的设备名称。
点击设备，右侧概要信息中的“Asset ID”即为
assetId。
如何获取测点（pointId）信息
在EnOS Console左边导航栏中点击 资产树，选择目标资产树，搜索想要查询的设备名称。
点击设备，右侧测点栏中的测点名称对应的标识符即为
pointId。
如何获取AccessKey（accessKey）信息
accessKey 是EnOS分配给应用的服务账号，用于对应用进行鉴权。accessKey通过注册应用获取。如需获取该信息，执行以下操作：
在EnOS Console左边导航栏中点击 应用注册。
选择需调用API的应用，查看基本信息中的“AccessKey”。
如何获取User ID（userId）信息
点击EnOS Console页面右上角用户头像。
在弹窗中查看当前用户的 用户ID，例如
u15426865866571。
projection参数如何对结果集做裁剪¶
projection参数用于对data结果集的裁剪，数据类型为String Array。其中每个String表示返回结果中需要返回的一个结果字段。没有在projection中指定的字段，在结果集中不返回。在指定字段时，可以使用：
符号 |
描述 |
|---|---|
|
表示一个Array中的每一个对象 |
|
表示任意字段值 |
|
表示子字段 |
例如有结果集：
[ {
"modelId": "planet",
"assetId": "TZ8AOlJU",
"timezone": "+00:00",
"name": {
"i18nValue": {
"en_US": "venus",
"zh_CN": "venus"
},
"defaultValue": "venus"
},
"attributes": {
"system": "Solar System",
"distances" : [ {
"towards": "sun",
"distance": "0.72 au"
}, {
"towards": "jupiter",
"distance": "5.44 au"
} ]
},
"modelIdPath": "/planet",
"orgId": "o1578468179",
"desc": null,
"tags": {}
},
{
"modelId": "planet",
"assetId": "CZ20AFJX",
"timezone": "+00:00",
"name": {
"i18nValue": {
"en_US": "mars",
"zh_CN": "mars"
},
"defaultValue": "mars"
},
"attributes": {
"system": "Solar System",
"distances" : [ {
"towards": "sun",
"distance": "1.58 au"
}, {
"towards": "venus",
"distance": "2.28 au"
} ]
},
"modelIdPath": "/planet",
"orgId": "o1578468179",
"desc": null,
"tags": {}
}
]
当用户只希望获取modelId，assetId，name中defaultValue和attributes中towards字段时，可以使用这样的裁剪参数：
"projection": [ "modelId", "assetId", "name.defaultValue", "attributes.distances[*].towards"]
裁剪后的返回结果集为：
[{
"modelId": "planet",
"assetId": "TZ8AOlJU",
"name": {
"defaultValue": "venus"
},
"attributes": {
"distances": [
{"towards": "sun"},
{"towards": "jupiter"}
]
}
},
{
"modelId": "planet",
"assetId": "CZ20AFJX",
"name": {
"defaultValue": "mars"
},
"attributes": {
"distances": [
{"towards": "sun"},
{"towards": "venus"}
]
}
}]
如何使用查询表达式¶
备注
此处列出所有支持的表达式语法。每个API在查询表达式中能够支持的字段与语法均不相同，具体需遵照各个API请求参数的说明使用。
API接口中支持以类SQL条件语句方式，指定查询条件，这种语句称为查询表达式。 查询表达式支持以下语法：
查询条件 |
表达式样例 |
描述 |
|---|---|---|
对于map类型变量，判断某键对应的值是否为指定值，用于筛选带有指定值的键值对 |
|
使用标签键值对，精确搜索带有指定标签的对象。 |
对于map类型变量，判断某特定的键是否存在，用于筛选带有指定键的标签 |
|
tags中存在“k1”的键，用于匹配标签键为“k1”的标签而忽略标签值的场景。 |
对于map类型变量，判断是否不存在某一个键，用于筛选不带有指定键的标签 |
|
tags中不存在“k2”的键，用于匹配标签键不是“k2”的标签而忽略标签值的场景。 |
判断一个字段是否等于一个值 |
|
|
判断一个字段的值，是否是一组值中的一个 |
|
|
判断一个字段是否不等于一个值 |
|
|
判断一个国际化名称字段是否模糊匹配一个值 |
|
|
|
|
|
使用 |
|
|
使用 |
|
|
国际化名称表示方法¶
在请求参数和返回结果中，使用国际化名称结构体表示国际化的名称。
国际化名称结构体¶
名称 |
数据类型 |
描述 |
|---|---|---|
defaultValue |
String |
缺省的名称 |
i18nValue |
Map（Key为String，Value为String） |
各个Locale下的名称，key为locale，value为各个locale下的名称。 |
defaultValue指，当使用的locale未在i18nValue中指定时，应当采用的名称。locale格式遵循Unicode locale identifier，例如”en_US”。有关更多信息，请参阅https://www.unicode.org/reports/tr35/tr35-55/tr35.html#BCP_47_Language_Tag_Conversion。
目前国际化名称只支持zh_CN 和en_US。
示例（接入服务等）
{
"defaultValue": "Turbine",
"i18nValue": {"zh_CN": "风机", "en_US": "Turbine"}
}
示例（Application Portal服务）
{
"default": "Turbine",
"en_US": "Turbine",
"zh_CN": "风机"
}
以上示例表示，当使用的locale为“zh_CN”时，名称为“风机”，当使用的locale为“en_US”时，名称为“Turbine”，当使用其他locale时，名称为“Turbine”。
时区表示方法¶
时区支持两种表示方式。
相对于UTC的time offset，例如“+08:00”或“-05:00”。在使用这种表示方式时，不支持夏令时。
遵循IANA TZ名称，例如“America / Los_Angeles”。 有关更多信息，请参阅https://en.wikipedia.org/wiki/List_of_tz_database_time_zones。
API中使用的时间戳¶
API返回结果中的时间戳，为UTC时区的Unix时间戳，单位为毫秒。
API中使用的时间参数¶
API请求参数中，以字符串方式指定时间，兼容localtime和UTC两种时间参数格式， localtime为日期时间字符串，UTC时间采用ISO8601标准格式。用户调用接口时，EnOS服务将按照约定的时间格式自动判断是localtime还是UTC时间，无需传入时区信息。
localtime采用的日期时间格式¶
数据类型 |
格式 |
示例值 |
说明 |
String |
YYYY-MM-DD HH:mm:ss |
2019-04-17 10:30:00 |
|
String |
YYYY-MM-DD HH:mm:ss.SSS |
2019-04-17 10:30:00.000 |
仅当API支持时 |
EnOS服务会根据被查询的资产上所配置的时区信息进行转换，如资产时区为UTC+0800，则2019-04-17 10:30:00 = 2019-04-17T10:30:00+0800 = UNIX时间戳1555468200。
考虑到夏令时的问题，由调用方根据响应结果集中的timestamp自行判断和处理。
平台转换时区需要额外的性能开销，特别是对于大量数据的请求查询，可能存在响应时间较长的情况，部分接口将视性能瓶颈做适当的限制。
UTC采用的ISO8601标准时间格式¶
数据类型 |
格式 |
示例值 |
String |
YYYY-MM-DD’T’HH:MM:ss’Z’ |
2019-04-17T02:30:00Z |
请求格式为UTC格式时，EnOS服务将按照UTC不带时区进行查询，即2019-04-17T02:30:00Z= UNIX时间戳 1555468200000。
标签的作用与表示方法¶
EnOS服务支持使用标签来管理对象，可以基于标签对对象进行搜索。标签采用Map（Key为String，Value为String表示）格式。
项目 |
描述 |
|---|---|
Key |
|
Value |
|
更新标签时需将其作为一个整体来更新。如已有标签“abc:123”。若要新增一个标签“bcd:234”，则需要将两个标签一起传入：{abc:123, bcd:234}。
模型路径的含义与表示方法¶
物模型之间可以具有继承关系，如：“双馈风机”物模型继承自“风机”物模型。API的请求参数和返回结果中使用模型路径表示模型之间的继承关系。
模型路径的数据类型为String。以“/”字符开头，同时以“/”字符连接继承路径上的各个模型ID。
例如，物模型model_x继承自model_y，model_y又继承自root_model_z，
那么model_x的模型路径是：“/root_model_z/model_y/model_x”
root_model_z的模型路径是：“/root_model_z”。
attributes的表示方法¶
资产具有一组静态属性，在API请求参数或返回结果中这组静态属性表示为Map（Key为String，Value为String、Integer、Number、Array或Object）。其中，Key为物模型中定义的属性Id，Value为属性的值。Value的类型参照物模型定义。你可以登陆 EnOS管理门户，在 设备管理 > 设备资产 > 设备详情 的 属性 标签页中查看属性ID及属性值。
如何指定一个设备¶
在API中可以通过两种方式指定一个设备资产：
通过
assetId通过
productKey与deviceKey
在API的请求参数中，一般会同时提供三个参数供用户指定一个设备资产。三个参数都是非必填参数，但是用户必须选择一种方式指定设备：
指定
assetId同时指定
productKey与deviceKey
名称 |
必需/可选 |
数据类型 |
描述 |
|---|---|---|---|
assetId |
可选 |
String |
资产ID |
productKey |
可选 |
String |
Product Key |
deviceKey |
可选 |
String |
Device Key |
如何获取资产树ID¶
每一棵资产树都有一个资产树ID。用户可以在控制台资产树下的资产树管理页面，查看每棵资产树的资产树ID。用户也可以通过Search Asset Tree接口获取OU下的所有资产树。有关资产树的详细信息，请查看资产树。
如何使用dataDefinition
dataDefinition是对同结构内datatype的数据定义。如当datatype为“String”时，dataDefinition会定义字符串的长度；当datatype为“enum”时，dataDefinition会定义枚举的取值及描述。
enum¶
当数据类型为 enum 时，dataDefinition 中会定义 enumDesc 结构体。其中包含的key为枚举的合法取值，value为该值的国际化描述。enumType 为枚举的类型，只允许INT和STRING。
示例
{
"enumDesc": {
"1": {
"defaultValue": "one",
"i18nValue": {
"en_US": "one",
"zh_CN": "一"
}
},
"2": {
"defaultValue": "two",
"i18nValue": {
"en_US": "two",
"zh_CN": "二"
}
}
},
"enumType": "INT",
"defaultValue":1
}
bool¶
当数据类型为 bool 时，dataDefinition 中会定义 boolDesc 结构体。其中”true”和”false”的value分别描述的true和false的含义。
示例
{
"boolDesc": {
"true": "开",
"false": "关"
},
"defaultValue":true
}
string¶
当数据类型为 string 时，dataDefinition 中会以 maxLength 来规定字串的最大长度，最长不超过1024位。
示例
{
"maxLength": 1024
}
struct¶
当数据类型为 struct 时，dataDefinition 中以 items 定义 struct 中的每个成员。
成员使用大括弧（{}）分隔，需要定义 identifier、name、dataType、dataDefinition、unit 和 required。
成员的 dataType 可以为除 struct 之外的任意类型。
示例：
{
"items":[
{
"identifier": "delta",
"name": {
"defaultValue": "delta",
"i18nValue": {
"en_US": "delta"
}
},
"dataType": "INT",
"dataDefinition":{
},
"unit": "rpm",
"required":true
}
]
}
array¶
当数据类型为 array 时，dataDefinition 中以 itemType 定义数组元素的数据类型。
itemType 只允许为“INT”、“FLOAT”、“DOUBLE”、或“STRING”。
示例
{
"itemType":"INT"
}
其他¶
当数据类型为int/float/double/timestamp/date/file时，dataDefinition 为“null”。
Item Format 示例¶
TSDB数据服务API中，可通过使用 itemFormat 参数，指定返回结果中测点数据的显示格式。可选值为0，1，2，每种显示格式的示例如下：
itemFormat=0¶
{
"code": 0,
"msg": "OK",
"data": {
"items": [
{
"assetId": "4DXYH7nS",
"localtime": "2019-06-11T18:35:12.123+08:00",
"timestamp": 1560249312446,
"power": "1.1236",
"dataQuality": "1.1236"
},
{
"assetId": "4DXYH7nS",
"localtime": "2019-06-11T18:35:12.123+08:00",
"timestamp": 1560249332446,
"windspeed": "1.1236",
"dataQuality": "1.1236"
}
]
}
}
itemFormat=1¶
{
"code": 0,
"msg": "OK",
"data": {
"items": [
{
"assetId": "4DXYH7nS",
"timestamp": 1560249312446,
"localtime": "2019-06-11T18:35:12.123+08:00",
"windspeed": "1.1236",
"power": "1.1236"
},
{
"assetId": "4DXYH7nS",
"timestamp": 1560249312446,
"localtime": "2019-06-11T18:35:12.123+08:00",
"windspeed": "1.1236",
"power": "1.1236"
},
{
"assetId": "4DXYH7nS",
"timestamp": 1560249312444,
"localtime": "2019-06-11T18:35:12.123+08:00",
"windspeed": "1.1236"
}
]
}
}
itemFormat=2¶
{
"code": 0,
"msg": "OK",
"submsg": " ",
"data": {
"items": [
{
"assetId": "xxx",
"pointId": "power",
"localTime": [
"2020-03-09T20:29:45.222 +08:00",
"2020-03-09T20:29:45.222 +08:00"
],
"timestamp": [
1583756985399,
1583756985399
],
"value": [
"12.3",
"17.8"
],
"dataQuality": [
0,
1"
]
}
]
}
}