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”。
projection
参数如何对结果集做裁剪¶
projection
参数用于对data
结果集的裁剪,数据类型为String Array
。其中每个String表示返回结果中需要返回的一个结果字段。没有在projection
中指定的字段,在结果集中不返回。在指定字段时,可以使用:
符号 |
描述 |
---|---|
|
表示一个Array中的每一个对象 |
|
表示任意字段值 |
|
表示子字段 |
例如有结果集:
[ {
"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": {}
}]
当用户只希望获取modelId
,assetId
和name
中defaultValue
字段时,可以使用这样的裁剪参数:
"projection": [ "[*].modelId", "[*].assetId","[*].name.defaultValue"]
裁剪后的返回结果集为:
[{
"modelId": "planet",
"assetId": "TZ8AOlJU",
"name": {
"defaultValue": "venus!"
}
},
{
"modelId": "planet",
"assetId": "CZ20AFJX",
"name": {
"defaultValue": "mars!"
}
}]
如何使用查询表达式¶
备注
此处列出所有支持的表达式语法。每个API在查询表达式中能够支持的字段与语法均不相同,具体需遵照各个API请求参数的说明使用。
API接口中支持以类SQL条件语句方式,指定查询条件,这种语句称为查询表达式。 查询表达式支持以下语法:
查询条件 |
表达式样例 |
描述 |
---|---|---|
判断标签中的一个键是否存在,用于筛选带有指定键的标签 |
|
tags中存在“k1”的键,用于匹配标签键为“k1”的标签而忽略标签值的场景。 |
判断标签中是否不存在某一个键,用于筛选不带有指定键的标签 |
|
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。
示例(接入服务等)
{
"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 |
2019-04-17 10:30:00 |
|
String |
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 |
2019-04-17T02:30:00Z |
请求格式为UTC格式时,EnOS服务将按照UTC不带时区进行查询,即2019-04-17T02:30:00Z= UNIX时间戳 1555468200000。
标签的作用与表示方法¶
EnOS服务支持使用标签来管理对象,可以基于标签对对象进行搜索。标签采用Map(Key为String,Value为String表示)格式。
更新标签时需将其作为一个整体来更新。如已有标签“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的类型参照物模型定义。
如何指定一个设备¶
在API中可以通过两种方式指定一个设备资产:
通过
assetId
通过
productKey
与deviceKey
在API的请求参数中,一般会同时提供三个参数供用户指定一个设备资产。三个参数都是非必填参数,但是用户必须选择一种方式指定设备:
指定
assetId
同时指定
productKey
与deviceKey
名称 |
是否必须 |
数据类型 |
描述 |
---|---|---|---|
assetId |
false |
String |
资产ID |
productKey |
false |
String |
Product Key |
deviceKey |
false |
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"
}
bool¶
当数据类型为 bool
时,dataDefinition
中会定义 boolDesc
结构体。其中”true”和”false”的value分别描述的true和false的含义。
示例
{
"boolDesc":{
"true": "开",
"false": "关"
}
}
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”。