API FAQs

如何获取组织ID(orgId)信息

在EnOS Console左边导航栏中点击身份与授权 > 组织信息。组织ID即为orgId。

如何获取模型标识符(modelId)信息

  1. 在EnOS Console左边导航栏中点击资产树,选择目标资产树,搜索想要查询的设备名称。

  2. 选择设备,点击右侧概要信息中模型名称后的查看,模型标识符即为modelId

如何获取Asset ID(assetId)信息

  1. 在EnOS Console左边导航栏中点击资产树,选择目标资产树,搜索想要查询的设备名称。

  2. 点击设备,右侧概要信息中的“Asset ID”即为assetId

如何获取测点(pointId)信息

  1. 在EnOS Console左边导航栏中点击资产树,选择目标资产树,搜索想要查询的设备名称。

  2. 点击设备,右侧测点栏中的测点名称对应的标识符即为pointId

如何获取AccessKey(accessKey)信息

accessKey是EnOS分配给应用的服务账号,用于对应用进行鉴权。accessKey通过注册应用获取。如需获取该信息,执行以下操作:

  1. 在EnOS Console左边导航栏中点击应用注册。

  2. 选择需调用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": {}
  }]

当用户只希望获取modelIdassetIdnamedefaultValue字段时,可以使用这样的裁剪参数:

"projection": [ "[*].modelId", "[*].assetId""[*].name.defaultValue"]

裁剪后的返回结果集为:

[{
    "modelId": "planet",
    "assetId": "TZ8AOlJU",
    "name": {
      "defaultValue": "venus!"
    }
 },
 {
    "modelId": "planet",
    "assetId": "CZ20AFJX",
    "name": {
      "defaultValue": "mars!"
    }
}]

如何使用查询表达式

备注

此处列出所有支持的表达式语法。每个API在查询表达式中能够支持的字段与语法均不相同,具体需遵照各个API请求参数的说明使用。

API接口中支持以类SQL条件语句方式,指定查询条件,这种语句称为查询表达式。 查询表达式支持以下语法:

查询条件

表达式样例

描述

判断标签中的一个键是否存在,用于筛选带有指定键的标签

exists(tags.k1)

tags中存在“k1”的键,用于匹配标签键为“k1”的标签而忽略标签值的场景。

判断标签中是否不存在某一个键,用于筛选不带有指定键的标签

not exists(tags.k2)

tags中不存在“k2”的键,用于匹配标签键不是“k2”的标签而忽略标签值的场景。

判断一个字段是否等于一个值

modelId = 'planet'

modelId 字段的值为“planet”。

判断一个字段的值,是否是一组值中的一个

modelId in ('planet', 'orbit')

modelId 字段的值为“planet”或“orbit”。

判断一个字段是否不等于一个值

state != 3

state 字段的值不等于“3”。

判断一个国际化名称字段是否模糊匹配一个值

name like '逆变器'

name 字段中模糊匹配“逆变器”。“光伏逆变器”、“逆变器2A”都被认作是对“逆变器”的模糊匹配。

name.en_US like 'capacity'

name 字段在en_US locale下模糊匹配 “capacity”。

使用 and 关键字连接多个查询表达式,表示需要同时满足多个条件

modelId = 'planet' and state = 2

modelId 字段的值为“planet”且 state 字段的值为“2”。

使用 or 关键字连接多个查询表达式,表示满足多个条件中的至少一个

modelId = 'planet' or state = 2

modelId 字段的值为“planet”或 state 字段的值为“2”。

国际化名称表示方法

在请求参数和返回结果中,使用国际化名称结构体表示国际化的名称。

国际化名称结构体

名称

数据类型

描述

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”。

时区表示方法

时区支持两种表示方式。

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表示)格式。

更新标签时需将其作为一个整体来更新。如已有标签“abc:123”。若要新增一个标签“bcd:234”,则需要将两个标签一起传入:{abc:123, bcd:234}。

模型路径的含义与表示方法

物模型之间可以具有继承关系,如:“双馈风机”物模型继承自“风机”物模型。API的请求参数和返回结果中使用模型路径表示模型之间的继承关系。

模型路径的数据类型为String。以“/”字符开头,同时以“/”字符连接继承路径上的各个模型ID。

例如,物模型model_x继承自model_ymodel_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

  • 通过productKeydeviceKey

在API的请求参数中,一般会同时提供三个参数供用户指定一个设备资产。三个参数都是非必填参数,但是用户必须选择一种方式指定设备:

  • 指定assetId

  • 同时指定productKeydeviceKey

名称

是否必须

数据类型

描述

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 中的每个成员。

成员使用大括弧({})分隔,需要定义 identifiernamedataTypedataDefinitionunitrequired。 成员的 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”。