有关 EnOS™ Edge API¶
EnOS™ Edge 开放涵盖系统各个核心业务流程的 REST API 接口。基于这些接口,开发者可以访问系统内的资源,开发各类应用。
- 有关 EnOS™ API 和 EnOS™ 提供的接口详细信息,参见 有关 EnOS™ API。
- 有关如何调用 EnOS™ API 的信息,参见 EnOS™ API 快速入门。
- 有关 EnOS™ Edge 的信息,参见 EnOS™ Edge。
API Request 结构¶
EnOS™ Edge API 请求包含以下组成部分:
Request URI¶
{URI-scheme}://{apigw-address}/{service-name}/{version}/{endpoint-URL}?{query-param=value}
其中:
URI-scheme
:协议,支持HTTP协议。apigw-address
:该EnOS™ Edge的API服务的IP地址或域名。service-name
:服务名称,如asset-service
。version
:API版本,如v2.0
。endpoint-URL
:资源及对资源的操作,如assets/update
。query-param
:对目标资源的选择条件,如orgId=1234
。当有多个query参数时,用&
符号连接。
以获取某OU内某个资产信息为例,API请求格式如下:
GET
http://{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中包含的参数指定了更新资产的时区、描述、标签等属性:
POST
http://{apigw-address}/asset-service/v2.1/assets?action=update&orgId=1234&isPatchUpdate=fasle
{
"asset": {
"modelId": "testModel",
"assetId": "123",
"timezone": "+08:00",
"description": "hahdesc",
"tags": {
"site": "Shanghai",
"producer": "ABC"
}
}
}
API Response结构¶
EnOS™ EdgeAPI的返回为以下格式的JSON结构体:
{
"code": 0,
"msg": "OK",
"requestId": "6cb7a013-7f83-4620-97c8-4695a892acdf",
"data": {
}
}
对返回参数的详细说明如下:
名称 | 是否必须 | 数据类型 | 描述 |
---|---|---|---|
code | true | Integer | API请求状态码,0表示请求成功。其它状态码的含义,参考公共返回码和API文档中的错误码解释。 |
msg | true | String | 对状态码的解释和说明。成功为“OK”。若API请求失败,返回具体错误信息。 |
requestId | true | String | 每次请求获取的id,用于唯一标识一次API请求。 |
data | false | Array 或 Object | API响应返回结果集,数据类型包括:基本数据类型、复杂类型或数组。 |
公共参数说明¶
对各API服务的公共参数说明如下。其他通用参数的获取和描述,详见API FAQs。
公共请求参数(接入服务等)¶
接入服务、模型服务、资产服务、事件服务、和资产树服务API的公共请求参数为:
Pagination请求结构体¶
Pagination参数表示随机分页。默认分页大小是10。
名称 | 是否必须 | 数据类型 | 描述 |
---|---|---|---|
pageNo | true | Integer | 请求页数,从1开始(Application Portal服务中的分页请求页数从0开始) |
pageSize | true | Integer | 每页记录数,必须大于0 |
sorters | false | Sorter结构体 | 分页排序方式(Application Portal服务暂不支持排序) |
Sorters结构体
名称 | 是否必须 | 数据类型 | 描述 |
---|---|---|---|
field | true | String | 分页字段名称 |
order | false | String | ASC表示正序排序、DESC表示倒序排序,默认为正序 |
Pagination参数示例
{
"pagination": {
"pageNo": 2,
"pageSize": 100,
"sorters": [{
"field": "assetId",
"order": "ASC"
}]
}
}
Projection参数¶
Projection参数用于对返回data结果集的裁剪,数据类型为String Array。其中每个String表示返回结果中需要返回的一个结果字段。没有在projection中指定的字段,在结果集中不返回。在指定字段时,可以使用:
符号 | 描述 |
[*] |
表示一个Array中的每一个对象 |
* |
表示任意字段值 |
. |
表示子字段 |
当不提供projection参数时,表示不对data结果集做裁剪。
Projection参数示例
{
"projection": [
"assetPaths”, “assets.*.assetId”
]
}
公共返回参数(接入服务等) ¶
接入服务、模型服务、资产服务、事件服务、和资产树服务API的公共返回参数为:
名称 | 是否必须 | 数据类型 | 描述 |
---|---|---|---|
pagination | false | 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 o15589291276361",
"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的公共返回码为:
错误码 | 错误信息 | 错误描述 |
---|---|---|
400 | You do not have permission for the following assets | 当前App对以下设备没有权限 |
400 | Exception: Invalid param accessKey | 参数accessKey有误 |
400 | xxx is required | xxx参数不能为空 |
400 | All asset authentication failed | 当前App对查询的所有设备都没有权限 |
400 | Invalid Argument | 参数无效或缺失 |
400 | [modelId] permission denied | [modelId]无效或无权限访问 |
430 | 请求超出服务内部的网络传输的最大限制 | |
701 | 服务出错 | |
702 | Params startTime or endTime is invalid, and date format of them should be consistent | 时间格式错误,local时间格式为YYYY-MM-DD HH:MM:SS;UTC时间格式需要加入时区信息,例如:2019-06-01T00:00:00+08:00 |
702 | xxx cannot be null or negative | 参数xxx不可为空或者为负数 |
702 | xxx is empty | 参数xxx不可为空 |
702 | Only one xxx is allowed | 参数xxx至多一个 |
702 | assetIds size * measurepoints size * pageSize is too large to query, result size may exceed RPC limit | 单次查询结果集过大,要求设备数*测点数*pageSize<=640000 |
702 | param xxx is invalid | 参数xxx无效 |
702 | endTime should not be later than startTime | 查询结束时间应比开始时间晚 |
702 | xxx is not a valid integer | 参数不是一个有效的整数类型 |
702 | assetId or measurement point does not match the model | 设备或测点与模型不匹配 |
702 | Please config/check storage group for org[] and model[] | 未配置存储策略或modelId有误 |