聚合数据（曲线）

接口说明

按小时 / 天 / 月聚合指定设备的多个因子，返回适合直接画曲线的数据。

	`/api/weather-data/list`	`/api/weather-data/avg`
返回内容	每次上报的明细	按时间桶聚合后的值
返回键名	英文因子名（`atc`）	中文因子名（`空气温度`）
时间字段	`createDate` 完整时间	`createDate` 时间桶标签
典型用途	导出明细、数据核对	画曲线、做日报

请求地址

text

GET https://yunshangwenshi.auto-control.com.cn/api/weather-data/avg

请求方法

GET

请求参数

参数名	类型	必填	说明	示例
`deviceId`	String	是	设备 ID（取自 `/api/device` 的 `id`）	`20612`
`fields`	String	是	要聚合的因子，英文缩写、逗号分隔	`atc,ahc,co2,light,stc,swc`
`groupType`	String	是	分组粒度：`HOUR` / `DAY` / `MONTH`	`HOUR`
`startTimestamp`	String	否	开始时间（毫秒级时间戳），默认当天 0 点	`1789207221385`
`endTimestamp`	String	否	结束时间（毫秒级时间戳），默认当前时间戳	`1789466421385`

groupType 只接受三个枚举值，传错会返回 500

实测传 groupType=YEAR：

json

{
  "code": 500,
  "message": "内部错误",
  "errorDetail": "No enum constant cc.liangjb.iot.common.constant.GroupTypeEnum.YEAR",
  "success": false
}

只允许 HOUR / DAY / MONTH，大小写敏感。

fields 传空不会报错，但只会返回空数组

实测不传 fields 时返回 code: 200 + data: []。 没有报错不代表调用正确 —— 请始终显式传入 fields。

fields 的取值

请参考因子对照表。可用因子包括 atc、ahc、co2、light、stc、swc、lp、ecfii、phfii 等。

请求头

请求头	值	必填
`Authorization`	`Bearer <token>`	是

返回字段

顶层

字段名	类型	说明	示例
`requestId`	String	请求唯一标识	`9c315651-a739-40bc-a83c-329a3a886ecd`
`code`	Int	状态码，`200` 为成功	`200`
`data`	Array	聚合结果数组，每个元素是一个时间桶	`[ {...} ]`
`timestamp`	Long	响应时间戳（毫秒）	`1789466326769`
`success`	Boolean	是否成功	`true`

时间桶对象（`data[]`）

这是「动态键」结构

每个时间桶对象的 key 是请求时 fields 里各因子对应的中文名，外加一个固定的 createDate。

字段名	类型	说明	示例
`createDate`	String	时间桶标签，格式随 `groupType` 变化（见下）	`09-12 18`
`<中文因子名>`	Number	该因子在此时间桶内的聚合值	`26.6`

`createDate` 的实测格式

这是最容易踩错的地方 —— 三种 groupType 返回三种完全不同的格式：

`groupType`	`createDate` 实测取值	含义
`HOUR`	`"09-12 18"`、`"09-12 19"`	月-日时
`DAY`	`"12"`、`"13"`、`"14"`、`"15"`	日
`MONTH`	`"09"`	月

createDate 不含年份

三种格式都不带年份。跨年查询时无法从 createDate 区分年份， 请结合你请求的 startTimestamp / endTimestamp 自行补全。

请求 `fields` ↔ 返回中文键对照

实测（控制器设备）：

请求 `fields`	返回体中文键
`atc`	空气温度
`ahc`	空气湿度
`stc`	土壤温度
`swc`	土壤湿度
`co2`	二氧化碳
`light`	光亮度

中文键与「历史数据」接口的 displayName 可能不同

同一因子在 /api/weather-data/list 里 displayName 可能是「土壤含水量」，在这里是「土壤湿度」。 做中英映射时请用 fields 里的英文因子名作为唯一键，不要依赖中文名。

请求示例

curl

bash

# 近 3 天，按小时聚合
curl 'https://yunshangwenshi.auto-control.com.cn/api/weather-data/avg?deviceId=20612&fields=atc,ahc,co2,light,stc,swc&groupType=HOUR&startTimestamp=1789207221385&endTimestamp=1789466421385' \
  -H "Authorization: Bearer <token>"

# 按天聚合
curl 'https://yunshangwenshi.auto-control.com.cn/api/weather-data/avg?deviceId=20612&fields=atc,ahc&groupType=DAY' \
  -H "Authorization: Bearer <token>"

HTTP 报文

http

GET /api/weather-data/avg?deviceId=20612&fields=atc,ahc,co2&groupType=HOUR HTTP/1.1
Host: yunshangwenshi.auto-control.com.cn
Authorization: Bearer <token>
Accept: application/json

Python

python

import requests

BIZ_HOST = "https://yunshangwenshi.auto-control.com.cn"

FACTOR_TO_CN = {
    "atc": "空气温度", "ahc": "空气湿度",
    "stc": "土壤温度", "swc": "土壤湿度",
    "co2": "二氧化碳", "light": "光亮度",
}


def query_avg(token: str, device_id, factors, group_type="HOUR",
              start_ms=None, end_ms=None):
    """按 group_type 聚合。返回原始的时间桶列表。"""
    params = {"deviceId": device_id, "fields": ",".join(factors), "groupType": group_type}
    if start_ms is not None:
        params["startTimestamp"] = start_ms
    if end_ms is not None:
        params["endTimestamp"] = end_ms

    resp = requests.get(
        f"{BIZ_HOST}/api/weather-data/avg",
        params=params,
        headers={"Authorization": f"Bearer {token}"},
        timeout=30,
    )
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(f"查询失败: {body.get('code')} {body.get('message')}")
    return body.get("data") or []


if __name__ == "__main__":
    buckets = query_avg("<你的 token>", 20612, ["atc", "ahc", "co2"], "HOUR")

    labels = [b["createDate"] for b in buckets]          # 形如 "09-12 18"
    series = {
        FACTOR_TO_CN[f]: [b.get(FACTOR_TO_CN[f]) for b in buckets]
        for f in ["atc", "ahc", "co2"]
    }
    print("时间轴:", labels[:5], "...")
    for name, values in series.items():
        print(f"{name}: {values[:5]} ...")

返回示例

`groupType=HOUR`

json

{
  "requestId": "9c315651-a739-40bc-a83c-329a3a886ecd",
  "code": 200,
  "data": [
    {
      "空气温度": 26.6, "土壤温度": 25.9, "光亮度": 0.0,
      "二氧化碳": 718.0, "空气湿度": 42.4, "土壤湿度": 32.1,
      "createDate": "09-12 18"
    },
    {
      "空气温度": 25.8, "土壤温度": 25.5, "光亮度": 0.0,
      "二氧化碳": 712.0, "空气湿度": 44.1, "土壤湿度": 32.0,
      "createDate": "09-12 19"
    }
  ],
  "timestamp": 1789466326769,
  "success": true
}

`groupType=DAY`

json

{
  "code": 200,
  "data": [
    { "空气温度": 26.6, "土壤温度": 25.9, "createDate": "12" },
    { "空气温度": 27.1, "土壤温度": 26.2, "createDate": "13" }
  ],
  "success": true
}

`groupType=MONTH`

json

{
  "code": 200,
  "data": [
    { "空气温度": 23.1, "土壤温度": 22.4, "createDate": "09" }
  ],
  "success": true
}

注意事项

返回键是中文

这是平台少数返回键为中文的接口。反序列化时：

Java：用 JsonNode / Map<String, Object>，不要用强类型 POJO
确保按 UTF-8 解析响应，否则中文键会乱码
想用英文键请在拿到后按因子对照表自行映射

缺失的时间桶不会补零

若某个时间桶没有数据，该桶可能不出现在数组里（而不是返回 null）。前端画曲线时建议按完整时间轴对齐补齐，避免曲线错位。

聚合算法未公开说明

接口名是 avg，实测数值也符合平均值量级，但平台未明确说明聚合算法。如果对口径有严格要求（例如需要最大值 / 累计值），请与运营方确认。

返回空数组的常见原因

该设备在该时间段没有历史数据（用历史数据先确认有数据）
fields 里的因子在这台设备上不存在
groupType 与时间范围不匹配（例如查一个月却用 HOUR，可能超出限制）

实测：同一账号下不同设备的结果可能完全不同

实测同一账号的两台设备：一台 3 天 HOUR 聚合返回 72 个桶，另一台返回 0 个桶（该设备没有历史数据落库）。遇到空数组时请换一台有数据的设备验证。

下一步

→ 因子（factor）对照表：查全部因子缩写
→ 历史数据：需要明细时用这个

聚合数据（曲线） ​

接口说明 ​

请求地址 ​

请求方法 ​

请求参数 ​

请求头 ​

返回字段 ​

顶层 ​

时间桶对象（data[]） ​

createDate 的实测格式 ​

请求 fields ↔ 返回中文键 对照 ​

请求示例 ​

curl ​

HTTP 报文 ​

Python ​

返回示例 ​

groupType=HOUR ​

groupType=DAY ​

groupType=MONTH ​

注意事项 ​

下一步 ​

聚合数据（曲线）

接口说明

请求地址

请求方法

请求参数

请求头

返回字段

顶层

时间桶对象（`data[]`）

`createDate` 的实测格式

请求 `fields` ↔ 返回中文键对照

请求示例

curl

HTTP 报文

Python

返回示例

`groupType=HOUR`

`groupType=DAY`

`groupType=MONTH`

注意事项

下一步