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