通用数据服务接口规范¶
通用数据服务为数据提供方提供统一的 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 的年级聚合数据。
- 时间范围为 2021-01-01 00:00:00 至 2021-01-05 00:00:00,
- 若