有关EnOS API¶

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

API 列表¶

EnOS提供以下API服务：

接入服务：开放EnOS系统在设备连接和设备管理领域的业务能力，包括产品和设备的创建和管理。
模型服务：支持搜索和获取组织内模型的详细信息。
资产服务：提供组织内资产的创建、管理、更新等服务。
告警服务：提供资产告警的查询和管理服务。
资产树服务：提供组织内资产树的创建、管理、更新、查询等服务。
TSDB数据服务：提供获取已存储的资产数据服务。
TSDB策略服务：提供获取TSDB存储策略配置信息的服务。
IAM服务：提供用户帐户生命周期管理，用户身份验证以及EnOS资源访问权限控制等服务。
Application Portal服务：通过获取用户、资产、应用的信息，在EnOS Application Portal上进行权限配置。
预测模型服务：部署“预测类”机器学习算法模型后，获取预测结果。
批处理服务：提供进行大数据分析时所需的数据集成、数据开发、和数据运维等服务。
数据联邦服务：提供多源异构数据存储系统的数据查询及文件写入服务。
流数据处理服务：提供流数据处理任务的查询和管理等功能。

API Request结构¶

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

Request URI¶

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

其中：

URI-sheme：协议，支持HTTPS协议。
apigw-address：API服务的网关地址。其范式为apim-{enos-environment}.{abc}.com，其中enos-environment为EnOS的部署环境名称。
service-name：服务名称，如asset-service。
version：API版本，如v2.0。
endpoint-URL：资源及对资源的操作，如assets/update。
query-param：对目标资源的选择条件，如orgId=1234。当有多个query参数时，用&符号连接。

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

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

Request Header¶

Request URI的REST 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 FAQs。

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	存在不正确的请求参数，具体信息请查看error message。
80401	Assset unauthorized	没有对设备的访问权限，检查对服务账号SA的授权。
80500	Internal server error	服务内部错误