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

通用数据服务接口规范


通用数据服务为数据提供方提供统一的 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 的年级聚合数据。