EnOS™ API 常见问题¶

如何获取组织 ID（`orgId`）信息 ¶

选择一种方式获取组织 ID：

在 EnOS 管理控制台左上角，将鼠标悬浮在组织名称上，悬浮窗上括号前的内容即为组织 ID（orgId）。
在 EnOS 管理控制台左边导航栏中点击 身份与授权 > 组织信息，查看组织 ID（orgId）。

如何获取模型标识符（`modelId`）信息 ¶

在 EnOS 管理控制台左边导航栏中点击 资产树，选择目标资产树，搜索想要查询的设备名称。
选择设备，点击右侧概要信息中模型名称后的查看，模型标识符即为 modelId。

如何获取 Asset ID（`assetId`）信息 ¶

在 EnOS 管理控制台左边导航栏中点击 资产树，选择目标资产树，搜索想要查询的设备名称。
点击设备，右侧概要信息中的 “Asset ID” 即为 assetId。

如何获取测点（`pointId`）信息 ¶

在 EnOS 管理控制台左边导航栏中点击 资产树，选择目标资产树，搜索想要查询的设备名称。
点击设备，右侧测点栏中的测点名称对应的标识符即为 pointId。

如何获取 AccessKey（`accessKey`）信息 ¶

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

在 EnOS 管理控制台左边导航栏中点击 应用注册。
选择需调用 API 的应用，查看基本信息中的 “AccessKey”。

如何获取 User ID（`userId`）信息 ¶

点击 EnOS 管理控制台页面右上角用户头像。
在弹窗中查看当前用户的 用户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 类型变量，判断某键对应的值是否为指定值，用于筛选带有指定值的键值对	`tags.{key}={value}`	使用标签键值对，精确搜索带有指定标签的对象。
对于 map 类型变量，判断某特定的键是否存在，用于筛选带有指定键的标签	`exists(tags.k1)`	tags 中存在 “k1” 的键，用于匹配标签键为 “k1” 的标签而忽略标签值的场景。
对于 map 类型变量，判断是否不存在某一个键，用于筛选不带有指定键的标签	`not exists(tags.k2)`	tags 中不存在 “k2” 的键，用于匹配标签键不是 “k2” 的标签而忽略标签值的场景。
对于 map 类型变量，判断某键对应的值是否模糊匹配，用于筛选带有模糊值的键值对	`tags.key like 'value'`	使用标签键值对，模糊搜索 tags 中键为 “key”，值为 “%value%” 的对象。
判断一个字段是否等于一个值	`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”。
在字符串中使用转义字符。	`a = "\'"` `a = "\""` `a = "\\"`	若需表达以下内容，按照左列中的示例使用转义字符。字符串中的单引号：`a = "'"` 字符串中的双引号：`a = """` 字符串中的反斜杠：`a = "\"`

国际化名称表示方法¶

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

国际化名称结构体¶

名称	数据类型	描述
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	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	仅支持英文、数字、下划线（_）、连字符（-）和斜杠（/）长度限制 50 个字符
Value	不得以空格作为值的开始或结尾长度限制 200 个字符

更新标签时需将其作为一个整体来更新。如已有标签 “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": "4DXYH7nS",
            "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"
            ]
         }
      ]
   }
}

如何对 API 搜索结果进行排序¶

你可以使用 Pagination 结构体中的 Sorter 结构体对搜索结果进行排序。注：并非所有的 API 都支持 Sorter 结构体。有关更多信息，请参阅 Pagination 结构体。