EnOS API 常见问题¶

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

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

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

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

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

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

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

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

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

如何获取资产树 ID¶

每一棵资产树都有一个资产树 ID。选择一种方式获取资产树 ID：

在 EnOS 管理控制台左边导航栏中点击 资产树，查看资产树 ID。
通过 Search Asset Tree API 获取 OU 下的所有资产树详细信息，包括资产树 ID。

如何获取 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	默认名称。当使用的 locale 未在 i18nValue 中指定时，采用默认名称。
i18nValue	Map（Key 为 String，Value 为 String）	国际化语言的名称，key 为 locale，value 为各个 locale 下的名称。locale 格式遵循 Unicode locale identifier，例如 “en_US”。

示例（接入服务等）

{
    "defaultValue": "Turbine",
    "i18nValue": {"zh_CN": "风机", "en_US": "Turbine"}
}

示例（应用门户服务）

{
        "default": "Turbine",
        "en_US": "Turbine",
        "zh_CN": "风机"
}

以上示例表示，当使用的 locale 为 “zh_CN” 时，名称为 “风机”，当使用的 locale 为 “en_US” 时，名称为 “Turbine”，当使用其他 locale 时，名称为 “Turbine”。

EnOS 支持的 locale¶

备注

可用的 locale 取决于当前环境的语言配置。如果某些语言在你的环境中不可用，可咨询系统管理员。

Locale	语言
zh_CN	简体中文
en_US	英语
ja_JP	日语
es_ES	西班牙语
de_DE	德语
fr_FR	法语
pl_PL	波兰语

时区表示方法¶

时区支持两种表示方式。

相对于 UTC 的 time offset，例如 “+08:00” 或 “-05:00”。在使用这种表示方式时，不支持夏令时。
遵循 IANA TZ 名称，例如 “America / Los_Angeles”。

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
Long	1555468200000	UTC 值 2019-04-17T02:30:00Z 的 UNIX 时间戳

请求格式为 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

如何使用 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 结构体。