有关 EnOS™ API¶

EnOS™ 开放涵盖系统各个核心业务流程的 Open API 接口。基于这些接口，开发者可以访问系统内的资源，开发各类应用。

API 适用范围¶

EnOS Cloud 和 EnOS Edge 都开放了涵盖系统各个核心业务流程的 Open API 接口。大部分 API 接口同时适用于 EnOS Cloud 和 EnOS Edge。在基于这些 API 接口开发应用之前，可通过每个 API 服务简介中的 API 列表，查看 API 接口的适用范围。

API 服务列表¶

EnOS 提供以下 Open API 服务：

模型服务：支持搜索和获取组织内模型的详细信息。
接入服务：开放 EnOS 系统在设备连接和设备管理领域的业务能力，包括产品和设备的创建和管理。
资产服务：提供组织内资产的创建、管理、更新等服务。
资产树服务：提供组织内资产树的创建、管理、更新、查询等服务。
告警服务：提供资产告警的查询和管理服务。
流数据处理服务：提供流数据处理任务的查询和管理等功能。
TSDB 策略服务：提供获取 TSDB 存储策略配置信息的服务。
TSDB 数据服务：提供获取已存储的资产数据服务。
数据联邦服务：提供多源异构数据存储系统的数据查询及文件写入服务。
数据资产目录服务：提供核心数据资产服务如数据对象搜索、数据详情查看、数据导入。
批处理服务：提供进行大数据分析时所需的数据集成、数据开发、和数据运维等服务。
Application Portal 服务：通过获取用户、资产、应用的信息，在 EnOS Application Portal 上进行权限配置。
业务流程管理服务：提供流程与任务的查询和管理服务。
消息推送管理服务：提供消息推送管理服务接口，开启推送消息推功能。
IAM 服务：提供用户帐户生命周期管理，用户身份验证以及 EnOS 资源访问权限控制等服务。
EnOS Edge 特有服务：提供支持 EnOS Edge 平台的特有 API。

API Request 结构¶

EnOS API 请求包含以下组成部分：

Request URI¶

{URI-scheme}://{apigw-address}/{service-name}/{version}/{endpoint-URL}?{query-param=value}

其中：

URI-sheme：协议，支持 HTTPS 协议。
apigw-address：EnOS Cloud API 或 EnOS Edge API 服务的 IP 地址或域名，可通过登入 EnOS 管理控制台，点击右上角的 帮助 > 环境信息 里 API 网关 中获取。
service-name：服务名称，如 asset-service。
version：API 版本，如 v2.0。
endpoint-URL：资源及对资源的操作，如 assets/update。
query-param：对目标资源的选择条件，如 orgId=1234。当有多个 query 参数时，用 & 符号连接。

以获取某组织内某个资产信息为例，API 请求格式如下：

GET https://{apigw-address}/asset-service/v2.1/assets?action=get&orgId=yourOrgId&assetId=abcd

Request Header¶

Request URI 中的 API 规范和 HTTP 规范所需的任何其他字段，绑定在 request header 中。

常用的 request header 为 Content-Type，代表数据提交方式，一般情况下它的值可设为 application/json;charset=UTF-8；若执行文件上传或其他表单提交，值设为 multipart/form-data;charset=UTF-8。

Request Body¶

用于补充 Request URI 以提供更加复杂的输入参数，如以下示例 request body 中包含的参数指定了更新资产的时区、描述、标签等属性：

url: https://{apigw-address}/asset-service/v2.1/assets?action=update&orgId=1234&isPatchUpdate=fasle

method: POST

requestBody:
{
  "asset": {
    "modelId": "testModel",
    "assetId": "123",
    "timezone": "+08:00",
    "description": "hahdesc",
    "tags": {
      "site": "Shanghai",
      "producer": "ABC"
    }
  }
}

API Response 结构¶

EnOS API 的返回为以下格式的 JSON 结构体：

{
  "code": 0,
  "msg": "OK",
  "requestId": "6cb7a013-7f83-4620-97c8-4695a892acdf",
  "data": {
  }
}

对返回参数的详细说明如下：

名称	数据类型	描述
code	Integer	API 请求状态码，0表示请求成功。其它状态码的含义，参考公共返回码和 API 文档中的错误码解释。
msg	String	对状态码的解释和说明。成功为 “OK”。若 API 请求失败，返回具体错误信息。
requestId	String	每次请求获取的 ID，用于唯一标识一次 API 请求。
data	Array 或 Object	API 响应返回结果集，数据类型包括：基本数据类型、复杂类型或数组。

公共参数说明¶

对各 API 服务的公共参数说明如下。其他通用参数的获取和描述，详见 API 常见问题。

Pagination 请求参数 ¶

Pagination 请求参数表示随机分页。默认分页大小是10。

名称	是否必需	数据类型	描述
pageNo	必需	Integer	请求页数，从1开始。（Application Portal 服务中的分页请求页数从 0 开始。）
pageSize	必需	Integer	每页记录数，必须大于0
sorters	可选	Sorter结构体数组	分页排序方式，支持多个排序方式，顺序靠前的排序方式，优先级更高。有关哪些API支持 `sorters` 、以及哪些字段可以用于 `sorters` 分页排序，见具体 API 的文档。

Sorters结构体

名称	是否必需	数据类型	必需/可选
field	必需	String	分页字段名称
order	可选	String	ASC 表示正序排序、DESC 表示倒序排序，默认为正序

Pagination参数示例

{
    "pagination": {
        "pageNo": 2,
        "pageSize": 100,
        "sorters": [{
            "field": "assetId",
            "order": "ASC"
        }]
    }
}

公共请求参数（接入服务等）¶

接入服务、模型服务、资产服务、事件服务、和资产树服务 API 的公共请求参数为：

Projection 参数¶

Projection 参数用于对返回data结果集的裁剪，数据类型为 String Array。其中每个 String 表示返回结果中需要返回的一个结果字段。没有在 projection 中指定的字段，在结果集中不返回。在指定字段时，可以使用：

符号	描述
`[*]`	表示一个 Array 中的每一个对象
`*`	表示任意字段值
`.`	表示子字段

当不提供 projection 参数时，表示不对 data 结果集做裁剪。

Projection 参数示例

{
    "projection": [
        "assetPaths”, “assets.*.assetId”
        ]
}

公共返回参数 ¶

各服务 API 的公共返回参数为：

名称	数据类型	描述
pagination	Pagination 响应结构体	当前返回结果的分页信息

公共返回码（接入服务等）¶

备注

此处仅列出公用的返回码，各接口特定的返回码需参阅具体 API 文档。

接入服务、模型服务、资产服务、事件服务、和资产树服务 API 的公共返回码为：

代码	描述
99400	请求参数非法，请检查请求参数。
99403	缺少权限，请检查是否有访问接口和请求资源的权限。
99404	指定的对象不存在。例如，在获取、更新、删除指定的设备时，指定的设备 deviceKey 不存在。
99500	服务器内部错误，请联系 EnOS 技术支持。

示例：

99400 错误示例：参数缺失
{
    "code": 99400,
    "msg": "Invalid Argument action:action is missing",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

99400 错误示例：参数错误
{
    "code": 99400,
    "msg": "Invalid Argument orgId: orgId does not exist",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

99403 错误示例：缺少权限
{
    "code": 99403,
    "msg": "Denied resource: orgId o1558xxxxxxxxxx",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

99500 错误示例：服务器内部错误
{
    "code": 99500,
    "msg": " Internal Server Error",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

公共返回码（TSDB数据服务）¶

备注

此处仅列出公用的返回码，各接口特定的返回码需参阅具体 API 文档。

TSDB 数据服务 API 的公共返回码为：

代码	错误信息	描述
0	OK	API 调用成功。
80400	Invalid param error	存在不正确的请求参数，具体信息请查看报错信息。
80401	Assset unauthorized	没有对设备的访问权限，检查对服务账号SA的授权。
80500	Internal server error	服务内部错误