EnOS 通用数据服务 API 概述¶

EnOS 通用数据服务 (Common Data Service) 对不同数据源进行注册和路由，解决数据“多源异构”问题，赋能应用开发。

通用数据服务 API 服务为数据消费者提供一站式、标准化、灵活可配的数据获取途径。应用开发者可通过通用数据服务 API 统一获取多种领域的规范数据，包括属性、测点、指标和资产等数据。关于通用数据服务 API 的完整接口列表及功能说明，参见 API 列表。

API 列表 ¶

你可以通过下表了解可以调用通用数据服务 API 执行哪些操作，每项操作对应的 URL，以及是否适用于 EnOS Cloud 和 EnOS Edge。

操作名称	描述	URL	适用于 EnOS Cloud	适用于 EnOS Edge
Query Meta Attribute	获取属性元数据	/cds-meta-service/v1.0/attribute?action=query	√	√
Query Meta Measurement Point	获取测点元数据	/cds-meta-service/v1.0/measurement-point?action=query	√	√
Query Meta Metric	获取指标元数据	/cds-meta-service/v1.0/metric?action=query	√	√
Query Meta Generic Data	获取通用元数据	/cds-meta-service/v1.0/generic?action=query	√	√
Query Meta Record	获取记录元数据	/cds-meta-service/v1.0/record?action=query	√	√
Query Accessible Asset Type	获取可访问的资产类型列表	/cds-asset-service/v1.0/accessible-asset-type?action=query	√	√
Query Accessible Asset	获取可访问的资产列表	/cds-asset-service/v1.0/accessible-asset?action=query	√	√
Query Asset Attribute	获取指定资产的属性	/cds-asset-service/v1.0/attribute?action=query	√	√
Query Asset Hierarchy	获取指定资产的层级关系	/cds-asset-service/v1.0/hierarchy?action=query	√	√
Query Asset Topology	获取指定资产的拓扑关系	/cds-asset-service/v1.0/topology?action=query	√	√
Query Asset Topology Rule	获取资产拓扑规则	/cds-asset-service/v1.0/topology/rule?action=query	√	√
Query Latest Measurement Point	获取最新的测点读数	/cds-realtime-service/v1.0/measurement-point/latest?action=query	√	√
Query Latest Metric	获取最新的指标数据	/cds-realtime-service/v1.0/metric/latest?action=query	√	√
Query Historical Measurement Point	获取测点的时序数据	/cds-timeseries-service/v1.0/tsdb-detail?action=query	√	√
Query Historical Metric	获取指标的历史数据	/cds-metric-service/v1.0/metric?action=query	√	√
Query Record	获取第三方记录数据	/cds-record-service/v1.0/record?action=query	√	√

API 请求¶

通用数据服务 API 请求包含请求 URI 和请求消息头两部分。

请求 URI¶

METHOD {URI-scheme}://{apigw-address}/{service-name}/{version}/{endpoint-URL}?{action=query&{}}

其中：

METHOD：请求方法。例如：GET 和 POST。
URI-scheme：API 协议。支持 HTTPS 协议。
api-gateway：API 服务的网关地址。例如：apim-xxx.enos-iot.com。可通过登录 EnOS 应用门户 > 开发者控制台，点击右上角的 帮助 > 环境信息 里 API 网关 中获取。
service-name：API 服务名称。例如：cds-metric-service。
version：API 版本。目前支持 v1.0。
endpoint-URL：资源和对资源的操作。例如：metric。
action=query&：查询参数，如果有多个参数，使用 & 作为分隔符。例如：action=query&orgId={yourOrgId}&mdmIds={yourMdmId}。

请求消息头（Header）¶

REST API 规范和 HTTP 规范所需的任何其他字段，绑定在请求消息头中。

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

请求示例¶

GET https://{api-gateway}/cds-asset-service/v1.0/accessible-asset-type?action=query&orgId=yourOrgId

API 返回结果¶

API 返回 JSON 结构体，格式如下。

{
    "msg": "OK",
    "code": 0,
    "data": [
      {
         "mdmType": "EnOS_Solar_Site",
         "domain": "solar",
         "domainName": "Solar",
         "isSite": true,
         "name": "exampleSolarSite"
      },
      {
         "mdmType": "EnOS_Solar_Inverter",
         "domain": "solar",
         "domainName": "Solar",
         "isSite": false,
         "name": "exampleSolarInverter"
      }
    ],
    "traceId": "1234567890abcdefghijkl0987654321"
}

对返回结果的详细说明如下。

名称	数据类型	描述
msg	String	对状态码的解释和说明。成功为 “OK”。若 API 请求失败，返回具体错误信息。
code	Integer	API 请求状态码，0 表示请求成功。有关状态码含义，参见返回码。
data	Array 或 Object	API 响应返回结果集。有关返回结果中响应参数的具体含义，参见各 API 参考文档。
traceId	String	API 响应事件的 ID，通常用于回溯通用数据服务对某次请求的响应过程，辅助故障排除。

返回码 ¶

通用数据服务 API 的返回码如下。

代码	描述
0	请求成功
95400	请求参数非法，请检查请求参数
95500	服务器内部错误，请联系系统管理员
95600	通用数据服务请求数据源服务时发生异常，请联系系统管理员

返回示例¶

失败示例。

{
    "msg": "[Error！: Asset Not found , Please check that the asset ID is correct. assetIds is [exampleAsset]]",
    "code": 95400,
    "traceId": "1234567890abcdefghijkl0987654321"
}

成功示例。

{
    "msg": "OK",
    "code": 0,
    "data": [
      {
         "mdmType": "EnOS_Solar_Site",
         "domain": "solar",
         "domainName": "Solar",
         "isSite": true,
         "name": "exampleSolarSite"
      },
      {
         "mdmType": "EnOS_Solar_Inverter",
         "domain": "solar",
         "domainName": "Solar",
         "isSite": false,
         "name": "exampleSolarInverter"
      }
    ],
    "traceId": "1234567890abcdefghijkl0987654321"
}