有关 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 服务。

通用 API¶

通用 API 是 EnOS 各核心业务流程中原生数据的 API 接口。通用 API 具有以下特点：

通用 API 提供通用的数据细节。通过通用 API，开发者可以获取数据本身，还可以根据需要获取该数据的来源、存储策略、处理状态等其他方面的数据，实现复杂的业务功能。
通用 API 支持灵活的数据处理方式。例如，使用通用 API 时，开发者传入模型标识符和资产树标识符，即可获取设备的模型信息和层级关系。除数据查询外，通用 API 还支持写入、删除数据，或触发、暂停、终止流程等。

EnOS 提供以下通用 API：

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

语义 API¶

语义 API 是基于业务语义将数据统一化、标准化后再输出的 API 接口。语义 API 具有以下特点：

语义 API 为开发者屏蔽因数据存储策略等带来的复杂性。例如，使用通用数据服务 API 时，开发者将设备和测点的标识符传入 TSDB 测点接口，即可获取设备测点数据，不受数据存储策略等限制。
语义 API 为数据赋予业务语义。使用语义 API 时，开发者可以从业务视角快速获取所需数据。例如，在使用接入工具 API 时，开发者传入风场 A 和风机类型的标识符，即可获取风场 A 下所有风机的信息。
语义 API 积累了跨领域的通用语义。对于适用于多种领域的数据，语义 API 可以将不同来源的同类数据进行整合，为开发者提供统一、规范的数据。

EnOS 提供以下语义 API：

接入工具服务：提供场站、设备和拓扑结构等数据的查询服务。
通用数据服务：提供属性、测点、指标和资产等数据的查询服务。

API Request 结构¶

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

Request URI¶

注解

设备预配置服务中的设备 API 是面向设备提供的 API 接口，使用特殊的 Request URI。更多信息，参见设备 API。

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

其中：

URI-scheme：协议，支持 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 开始。（应用门户服务 API 中的请求页数从 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	服务内部错误

SDK 示例¶

你可以在 GitHub 上获取 API 的 SDK 示例：

Java
Python