API Reference

数据对接 API

把外部能碳平台的采集数据,通过其只读 REST 查询接口定时接入本系统(设备遥测 / 月度电量)。

通道:采集引擎 HTTP 数据源 凭据走环境变量 端点与返回结构以系统实际实现为准

本版面向外部集成,仅保留接口契约(端点 / 请求 / 响应 / 字段),不含内部源码位置与实现细节。示例中的 <...> 均为占位符,接入时替换为真实值。

01对接架构

对方能源管理平台 只读 REST ingest HTTP 源定时拉取 · 增量游标 · 失败退避 点位映射 设备遥测 / 电力活动数据 碳核算/用电优化
  • 对方只需提供一个只读查询接口;字段差异由「点位映射」吸收,不要求对方改表或定制接口。
  • 数据两种去向:
    • target=telemetry:写入设备遥测,同时刷新设备实时状态(功率 / 温度 / 设定值等)。
    • target=activity:按电表示值累计增量,周期性汇总成一条电力活动数据,进入碳核算。
  • 另有旁路分析通道(直连对方 MySQL / TDengine,只读、按需查询),与本文的定时采集互补,不在本文展开。

02鉴权与租户

所有 /api/ec/* 接口需登录令牌,按登录租户隔离数据。

2.1 登录取令牌

POST /api/auth/login
http
POST /api/auth/login
Content-Type: application/json

{ "username": "<用户名>", "password": "<密码>" }

响应:

json
{ "token": "<令牌>", "user": { "username": "...", "tenant": "default", "tenant_name": "..." } }

2.2 携带令牌

后续请求只从 Authorization 头取令牌(不支持 ?token= 传参,避免进访问日志):

http
Authorization: Bearer <令牌>

2.3 错误返回约定

统一为 HTTP 状态码 + JSON:

状态码body触发
401{"error": "..."}令牌缺失 / 失效
404{"error": "not found"}路由不存在
400{"error": "异常类型: 描述"}参数校验失败 / 引擎抛错(如 HTTP 源缺少 path)

03对方平台需提供的 REST 接口契约

本系统作为客户端去调对方接口。对方接口需满足:

项要求
协议HTTP / HTTPS,返回 JSON
方法GET(默认)/ POST / PUT / PATCH
鉴权Bearer token(配 auth_env)或自定义头(配 headers,值支持 env:NAME)
数据数组响应中有一个记录数组,路径可配(list_path,默认 data)
增量(可选)支持按游标/时间戳增量查询(cursor_param),响应回传新游标(cursor_field)
只读本系统只读取,不对对方接口做任何写操作

响应示例(对方提供,字段名仅为示意):

json
{
  "code": 0,
  "data": [
    { "device_id": "chiller-1", "active_power": 186.5, "meter_reading": 12345.6, "ts": "2026-11-08T10:00:00" }
  ],
  "next_cursor": "2026-11-08T10:00:00"
}

04数据源管理接口

基础路径 /api/ec,均需 Bearer 令牌。

4.1 建立数据源

POST /api/ec/ingest/sources

请求体见 §5 字段表。响应:

json
{ "source": { "id": "platform-rest", "kind": "http", "host": "https://...", "path": "/api/v1/...", "points": [ ... ], "...": "..." } }

校验失败返回 400,常见消息:

  • HTTP 源的 host 必须是 http:// 或 https:// 开头的地址
  • HTTP 源缺少 path
  • HTTP 源的 method 只支持 GET / POST / PUT / PATCH
  • 环境变量 XXX 未设置或为空(凭据不要写进配置)
  • 数据源 xxx 已存在

4.2 列出数据源

GET /api/ec/ingest/sources
json
{ "sources": [ { "id": "...", "kind": "http", "...": "..." } ] }

4.3 采集状态

GET /api/ec/ingest/status
json
{
  "enabled": true,
  "interval_s": 60,
  "flush_interval_s": 3600,
  "running": true,
  "sources": [
    { "id": "platform-rest", "name": "能碳平台 REST", "kind": "http", "enabled": true,
      "host": "https://...", "port": 443, "points": 2, "url": "https://.../api/v1/...",
      "last_ts": "2026-11-08T10:00:00", "last_ok": true, "last_error": "", "last_records": 12,
      "cursor": "2026-11-08T10:00:00", "fails": 0, "next_retry_at": "" }
  ],
  "accum": {},
  "pending_kwh": 0.0,
  "recent": [ { "ts": "...", "source_id": "...", "ok": true, "records": 12, "error": "" } ]
}

4.4 连通性测试(不落数据)

GET /api/ec/ingest/test/{source_id}

成功:

json
{ "ok": true, "kind": "http", "records": 12,
  "sample": [ { "raw_keys": ["active_power", "device_id", "meter_reading", "ts"], "power_kw": 186.5 } ],
  "cursor": "2026-11-08T10:00:00" }

失败:{ "ok": false, "kind": "http", "error": "HttpError: ..." }

用途:建源后先跑它,确认 list_path / json_key 映射对了再正式采集。

4.5 追加点位映射

POST /api/ec/ingest/sources/{source_id}/points

请求体见 §6 点位字段表。响应:

json
{ "point": { "metric": "power_kw", "json_key": "active_power", "target": "telemetry", "...": "..." } }

4.6 启用 / 禁用源

POST /api/ec/ingest/sources/{source_id}/enable → enabled: true
POST /api/ec/ingest/sources/{source_id}/disable → enabled: false
json
{ "source": { "...": "...", "enabled": true } }

4.7 试采一轮(落数据)

POST /api/ec/ingest/poll
json
{ "source_id": "platform-rest", "flush": true }
  • source_id 留空则采所有启用的源;flush=true 时采完立即汇总活动数据。
json
{
  "results": [
    { "source_id": "platform-rest", "kind": "http", "ok": true,
      "records": [ { "device_id": "chiller-1", "metric": "power_kw", "target": "telemetry", "value": 186.5, "ts": "..." } ],
      "error": "", "cost_ms": 230, "ts": "..." }
  ],
  "flushed": 1
}

失败 / 退避跳过时 ok=false,带 error、backoff_s 或 skipped=true。

4.8 汇总活动数据

POST /api/ec/ingest/flush → { "flushed": 3 }

把累计的电表示值增量汇总成电力活动数据(进碳核算)。

4.9 启动 / 停止定时采集

POST /api/ec/ingest/start { "interval_s": 60 } → { "started": true }
POST /api/ec/ingest/stop → { "stopped": true }
  • interval_s 缺省用配置值(默认 60s 采集、3600s 汇总)。已在运行时 started=false。

4.10 删除数据源

DELETE /api/ec/ingest/sources/{source_id} → { "removed": true }

05HTTP 源配置字段(建源请求体)

字段必填说明
id是源唯一标识
kind是固定 http(另支持 modbus / mqtt)
host是基地址,必须 http:// 或 https:// 开头
path是资源路径,如 /api/v1/meters/readings
name否显示名,缺省用 id
method否GET(默认)/ POST / PUT / PATCH
enabled否默认 true
port否https 默认 443,http 默认 80
timeout否超时秒,默认 10
headers否额外请求头;值支持 env:NAME 引用环境变量
params否固定查询参数(对象)
json_body否POST/PUT/PATCH 的 JSON 请求体
auth_env否环境变量名,存在时追加 Authorization: Bearer <值>;建源时该变量必须已设置
list_path否响应中数据数组的路径,默认 data;取不到则把整个响应当数组
cursor_param否增量参数名(如 since),把上次水位线带上去
cursor_field否水位线来源:next_cursor 取响应同名字段;其它值按该路径取记录最大值
device_id否固定设备号(响应无设备字段时用)
device_id_from否从响应取设备号的路径,默认 payload.device_id
ssl_verify否默认 true;对方自签证书时才设 false
points否点位映射数组,见 §6(也可建源后用 4.5 追加)

凭据红线:密码 / token 不写进配置,只留环境变量名(auth_env 或 headers 的 env:NAME)。

06点位映射字段

字段必填说明
metric是本系统指标名,如 power_kw / energy_kwh / temp / setpoint
json_key否对方响应里的字段路径(支持 a.b.c),缺省用 metric
target否telemetry(默认,刷设备实时状态)或 activity(累计电量进核算)
name否点位显示名,缺省用 metric
device_id否该点位固定设备号(覆盖源级取值)
scale否乘法换算系数,默认 1
offset否加法偏移,默认 0

换算公式:value = 原始值 × scale + offset。非数值原始值会被跳过。

示例:

json
[
  { "metric": "power_kw",   "json_key": "active_power",  "target": "telemetry", "scale": 1 },
  { "metric": "energy_kwh", "json_key": "meter_reading", "target": "activity" }
]

07增量游标与容错

  • 游标推进:水位线由系统按源保存,请求时作为 cursor_param 带上;采集成功才推进,失败不推进,避免中间数据永久丢失。
  • 失败退避:连续失败按退避间隔跳过,上限 900s(对方多半停机维护);状态见 status 的 fails / next_retry_at。
  • 单源隔离:一个源异常不影响其它源采集。

08完整对接示例(curl 四步)

替换 <你的服务地址>、<用户名>、<密码>、https://对方平台地址、路径与字段为真实值;先在启动环境设好 PLATFORM_TOKEN。

bash
BASE=https://<你的服务地址>

# 0) 登录取令牌
TOKEN=$(curl -s $BASE/api/auth/login -H 'Content-Type: application/json' \
  -d '{"username":"<用户名>","password":"<密码>"}' | python -c 'import sys,json;print(json.load(sys.stdin)["token"])')
AUTH="Authorization: Bearer $TOKEN"

# 1) 建源
curl -s $BASE/api/ec/ingest/sources -H "$AUTH" -H 'Content-Type: application/json' -d '{
  "id":"platform-rest","name":"能碳平台 REST","kind":"http",
  "host":"https://对方平台地址","path":"/api/v1/meters/readings","method":"GET",
  "auth_env":"PLATFORM_TOKEN","list_path":"data",
  "cursor_param":"since","cursor_field":"next_cursor",
  "device_id_from":"payload.device_id",
  "points":[
    {"metric":"power_kw","json_key":"active_power","target":"telemetry"},
    {"metric":"energy_kwh","json_key":"meter_reading","target":"activity"}
  ]}'

# 2) 连通测试(不落数据,先看映射对不对)
curl -s $BASE/api/ec/ingest/test/platform-rest -H "$AUTH"

# 3) 试采一轮并汇总
curl -s $BASE/api/ec/ingest/poll -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"source_id":"platform-rest","flush":true}'

# 4) 起定时采集
curl -s $BASE/api/ec/ingest/start -H "$AUTH" -H 'Content-Type: application/json' -d '{"interval_s":60}'

09接口速查表

方法路径用途
POST/api/auth/login登录取令牌
POST/api/ec/ingest/sources建源
GET/api/ec/ingest/sources列源
GET/api/ec/ingest/status采集状态
GET/api/ec/ingest/test/{id}连通测试(不落数据)
POST/api/ec/ingest/sources/{id}/points追加点位
POST/api/ec/ingest/sources/{id}/enable启用源
POST/api/ec/ingest/sources/{id}/disable禁用源
POST/api/ec/ingest/poll试采一轮
POST/api/ec/ingest/flush汇总活动数据
POST/api/ec/ingest/start起定时
POST/api/ec/ingest/stop停定时
DELETE/api/ec/ingest/sources/{id}删源