EnOS 通用数据服务 API 概述¶

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

通用数据服务 API 服务为数据消费者提供一站式、标准化、灵活可配的数据获取途径。

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

API 服务列表¶

通用数据服务提供以下 Open API 服务。

操作名称	描述	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 服务。

操作名称	企业版	轻量版
Query Meta Attribute	√	√
Query Meta Measurement Point	√	√
Query Meta Metric	√	√
Query Meta Generic Data	√	√
Query Meta Record	√	√
Query Accessible Asset Type	√	√
Query Accessible Asset	√	√
Query Asset Attribute	√	√
Query Asset Hierarchy	√	√
Query Asset Topology	√	√
Query Asset Topology Rule	√	√
Query Latest Measurement Point	√	√
Query Latest Metric	√	√
Query Historical Measurement Point	√	√
Query Historical Metric	√	√
Query Record	√	√

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 服务的网关地址。例如：app-portal-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"
}