EnOS 接入工具 API 概述¶

EnOS 接入工具（Onboarding Tool）面向终端用户提供一站式、多领域、分权限的自动化资产接入功能，支持不同业务和领域的资产接入和管理。更多信息，参见 EnOS 接入工具。

接入工具 API 服务提供对场站、设备、拓扑结构的信息查询等操作。

有关如何调用 EnOS API 的信息，参见 EnOS API 快速入门。

Java SDK¶

如果要在工程中使用 amc-api-pojo，则需要在 pom.xml 文件中添加以下依赖（需适时更新其版本）。

<dependency>
  <groupId>com.envisioniot.enos</groupId>
  <artifactId>amc-api-pojo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

API 服务列表¶

接入工具 API 提供以下 Open API 服务：

API 名称	描述	适用于 EnOS Cloud	适用于 EnOS Edge
Search Site	查询场站的基本信息	√	×
Search Device	查询全部或指定场站下设备的基本信息	√	×
Search Topology	查询场站内拓扑结构的基本信息	√	×
Search Topology Path	查询拓扑结构从根到最末的节点路径，并返回路径中所有节点的信息	√	×
Get Topology Definition	获取拓扑结构的元数据，以及拓扑规则允许的设备类型等信息	√	×

API 请求结构¶

接入工具 API 请求包含以下部分。

请求 URI¶

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

其中:

METHOD：请求方法。例如：GET 和 POST。
URI-scheme：协议，支持 HTTPS 协议。
apigw-address：API 服务的网关地址，该信息可通过登录 EnOS 管理控制台, 在 帮助 > 环境信息 的 API 网关 中获取。
service-name：当前服务名称，接入工具服务名称为 amc。
version：API 版本，使用 v1.0。
endpoint-URL：资源及对资源的操作，如 site 或 topology。
query-param：对目标资源的选择条件，当有多个 query 参数时，用 & 符号连接。例如 action=search&orgId=YourOrgId。

请求 Header
¶

请求 URI 中的 API 规范和 HTTP 规范所需的任何其他字段，绑定在请求 Header 中。

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

请求 Body¶

请求 Body 用于补充请求 URI，以提供更复杂的输入参数，如以下示例请求 Body 中包含的参数指定了查询设备的拓扑信息和设备类型。

URL: https://{apigw-address}/amc/v1.0/device?action=search?orgId=yourOrgId

method: POST

requestBody:
{
    "queryTopologyParams":{
        "parentAssetId":"x4zeFkkf",
        "topologyId":"you topology Id"
    },
    "deviceTypes":[
        "WeatherStation"
    ]
}

API 返回结构¶

接入工具 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 响应返回结果集，数据类型包括：基本数据类型、复杂类型或数组。

返回示例¶

返回失败示例：

{
    "code": 99500,
    "msg": "Internal Server Error",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

返回成功示例：

{
    "code":0,
    "msg":null,
    "requestId":"f3bf3b13-058a-481d-88c0-06087fd36554",
    "data":[
        {
            "assetId":"HnfxM8Rc",
            "name":{
                "defaultValue":"123",
                "i18nValue":{

                }
            },
            "modelId":"EnOS_Solar_Site",
            "timezone":"+08:00",
            "description":null,
            "attributes":{
                "altitude":123,
                "latitude":123,
                "combinerBoxAmount":1,
                "capacity":123,
                "omtAmount":1,
                "bxtfAmount":1,
                "emtAmount":1,
                "wstAmount":1,
                "acCbxAmount":2,
                "equipmentAmount":1,
                "gmtAmount":1,
                "strInvAmount":0,
                "longitude":123
            },
            "tags":{
                "amc_source":"amc",
                "amc_deviceType":"SolarSite",
                "amc_classType":"Site"
            },
            "typeInfo":{
                "identifier":"SolarSite",
                "name":{
                    "defaultValue":"Solar Site",
                    "i18nValue":{

                    }
                },
                "type":"Site"
            }
        }
    ],
    "pagination":{
        "sortedBy":null,
        "pageNo":1,
        "pageSize":100,
        "totalSize":1
    }
}