• 文档
• 通用数据服务接口规范

通用数据服务接口规范

通用数据服务为数据提供方提供统一的 API 接口规范，只有按照规范完成标准化的接口才能注册为通用数据服务的数据源。有关如何注册数据源，参见 注册数据源。

通用数据服务支持注册 指标、累计型测点、属性 和 记录 类型的接口。以下分别介绍所有类型接口需遵循的通用规范，以及每个类型接口需遵循的特殊规范。

通用规范

指标、累计型测点、属性 和 记录 类型的接口均需遵守以下规范：

• 请求成功的返回码为 0。

• 通用数据服务无需鉴权，即可调用数据源接口获取数据。

• 若需同时提供历史、当日及未来数据，采用以下两种 方案之一 ：

  • 搭配使用 指标 接口与 累计型测点 接口，前者提供历史数据，后者提供当日及未来数据。除非用于计划发电量未来数据等特殊场景，否则请勿通过 指标 接口返回当日及未来的数据。

  • 通过 指标 接口提供当日及未来数据，不单独提供 累计型测点 接口。

• 指标 和 累计型测点 接口中 timeGroup（聚合时间粒度）参数的时间返回格式规范如下。

  时间粒度	含义	时间返回格式	示例
  RAW	原始数据	YYYY-MM-DD hh:mm:ss	2021-03-25 00:00:01
  1m	1 分钟	YYYY-MM-DD hh:mm:ss	2021-03-25 00:01:00
  5m	5 分钟	YYYY-MM-DD hh:mm:ss	2021-03-25 00:05:00
  10m	10 分钟	YYYY-MM-DD hh:mm:ss	2021-03-25 00:10:00
  15m	15 分钟	YYYY-MM-DD hh:mm:ss	2021-03-25 00:15:00
  30m	30 分钟	YYYY-MM-DD hh:mm:ss	2021-03-25 00:30:00
  H	小时	YYYY-MM-DD hh:mm:ss	2021-03-25 01:00:00
  D	日	YYYY-MM-DD	2021-03-25
  W	周	YYYY-Wxx	2021-W12
  M	月	YYYY-MM	2021-03
  Q	季	YYYY-Qx	2021-Q1
  Y	年	YYYY	2021
  T	总计	1970	1970
  L	最新数据	YYYY-MM-DD hh:mm:ss	2021-03-25 00:00:01

• 指标 接口中，返回结果的规范根据 timeGroup（聚合时间粒度）参数有所不同：

  • 若 timeGroup 为 L，请求参数中的 startTime（开始时间）和 endTime（结束时间）免传，当请求的多个指标的时间不一致时，接口需直接返回最晚的时间。

  • 若 timeGroup 为 L 以外的其他时间粒度，请求时会指定时间范围，接口需按照粒度返回左闭右闭区间数据。例如发电量指标支持 D、M、Y 三个聚合粒度，不同场景下需返回的数据如下：

    • 时间范围为 2021-01-01 00:00:00 至 2021-01-05 00:00:00，timeGroup 为 D，则返回 2021-01-01 至 2021-01-05 的天级数据。

    • 时间范围为 2021-01-05 00:00:00 至 2021-02-05 00:00:00，timeGroup 为 M，则返回 2021-01-05 至 2021-01-31、2021-02-01 至 2021-02-05 的月级聚合数据。

    • 时间范围为 2020-01-05 00:00:00 至 2021-02-05 00:00:00，timeGroup 为 Y，则返回 2020-01-05 至 2020-12-31、2021-01-01 至 2021-02-05 的年级聚合数据。

特殊规范

• 指标接口规范

• 累计型测点接口规范

• 属性接口规范

• 记录接口规范