📚 课程目录第4章 EcoStruxure REST API基础与认证

4. EcoStruxure REST API基础与认证

EcoStruxure 的开放能力主要通过 REST API 暴露给上层应用。REST 的核心思想是“用 URL 定位资源、用 HTTP 方法表达动作、用状态码表达结果”。要真正把接口用起来，第一步不是写业务逻辑，而是把三件事弄清楚：端点长什么样、身份怎么证明、数据怎么装进请求和响应。本节围绕这三点展开，并给出可直接套用的调用样例。

一、API 端点结构：从基址到资源路径

EcoStruxure 的 REST 端点通常遵循统一的分层结构，可以拆成五段来看：

https://{host}/api/{version}/{resource}/{id}?{query}

示例：
https://ecostruxure.example.com/api/v1/sites/8a3f-1024/measurements?type=activePower&from=2024-06-01T00:00:00Z&to=2024-06-01T01:00:00Z&page=1&pageSize=100

host（主机）：区分区域与租户环境，例如生产、预生产、沙箱使用不同域名，切换环境时只需替换 host。
version（版本）：如 v1、v2，用于接口演进时的兼容控制，升级前应确认目标版本是否仍受支持。
resource（资源）：名词复数形式，如 sites、devices、measurements、alarms，代表一类对象集合。
id（资源标识）：定位集合中的单个对象，如 /sites/{siteId}/devices/{deviceId}，体现父子层级关系。
query（查询参数）：以 ? 开始、用 & 连接，控制过滤、分页、排序与字段裁剪。

需要特别注意的是层级嵌套：站点下挂设备、设备下挂测点，路径会逐级展开。层级越深，单次请求返回的数据越聚焦，但也意味着必须先拿到父级 ID。实践中建议先调用集合接口获取 ID 列表，再按 ID 深入子资源，而不是凭猜测拼接路径。

二、认证：OAuth 2.0 与 API Key 的分工

EcoStruxure 同时支持两类认证方式，适用场景不同。

API Key 适合服务端到服务端的简单集成或调试。它是一串长期有效的密钥，通常放在请求头中：

GET /api/v1/sites HTTP/1.1
Host: ecostruxure.example.com
X-API-Key: 7f3c9a2e-4b81-4d6f-9c02-1a5e8b7d3f60
Accept: application/json

API Key 的优点是接入快，缺点是权限粒度粗、泄露后影响面大，因此不应写入前端代码或公开仓库，建议配合 IP 白名单使用。

OAuth 2.0 适合需要细粒度授权、多用户或第三方接入的场景。EcoStruxure 常用的是客户端凭证模式（client_credentials），流程为：客户端用 client_id 与 client_secret 换取 access_token，再携带该令牌访问资源。令牌有有效期，过期需重新获取或使用 refresh_token 续期。

POST /oauth2/token HTTP/1.1
Host: ecostruxure.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=my-integration
&client_secret=S3cr3t-Value
&scope=read:sites read:measurements

响应：
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:sites read:measurements"
}

拿到令牌后，后续请求统一在 Authorization 头中携带：

GET /api/v1/sites HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

scope 决定令牌能访问哪些资源，申请时应遵循最小权限原则。若返回 401，说明令牌缺失、过期或无效；若返回 403，则说明令牌有效但权限不足，两者要区分排查。

三、请求与响应格式：JSON 为主，XML 兼容

EcoStruxure REST API 默认使用 JSON，通过 Content-Type 与 Accept 头协商格式。请求体为 JSON 时，必须显式声明 Content-Type: application/json；若服务端仅支持 XML，则使用 application/xml。响应格式由 Accept 决定，建议始终显式声明，避免依赖默认值。

POST /api/v1/sites HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "name": "上海工厂A区",
  "timezone": "Asia/Shanghai",
  "tags": ["production", "line-1"]
}

成功响应通常返回 201 Created 并携带新建资源：

{
  "id": "8a3f-1024",
  "name": "上海工厂A区",
  "timezone": "Asia/Shanghai",
  "createdAt": "2024-06-01T08:12:33Z",
  "links": { "self": "/api/v1/sites/8a3f-1024" }
}

错误响应结构相对统一，便于程序化处理：

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "from 必须早于 to",
    "target": "from",
    "details": [{ "reason": "time_range_invalid" }]
  }
}

解析时应先判断 HTTP 状态码，再读取 error.code 做分支处理，不要仅凭 message 文本匹配，因为文本可能随语言或版本变化。

四、分页与过滤参数

集合接口返回的数据量可能很大，必须使用分页。EcoStruxure 常见分页参数为 page 与 pageSize，响应中会给出总数与翻页链接：

GET /api/v1/devices?page=2&pageSize=50

{
  "items": [ ... ],
  "page": 2,
  "pageSize": 50,
  "total": 1240,
  "links": {
    "self": "/api/v1/devices?page=2&pageSize=50",
    "next": "/api/v1/devices?page=3&pageSize=50",
    "prev": "/api/v1/devices?page=1&pageSize=50"
  }
}

过滤参数用于缩小结果集，常见的有：时间范围 from/to（ISO 8601 UTC 格式）、类型 type、状态 status、标签 tags、排序 sort。多个过滤条件之间为 AND 关系。例如查询某设备在指定小时内类型为有功功率的测点：

GET /api/v1/devices/{deviceId}/measurements
    ?type=activePower
    &from=2024-06-01T00:00:00Z
    &to=2024-06-01T01:00:00Z
    &sort=-timestamp
    &page=1&pageSize=200

实践中有三点经验：一是时间统一用 UTC，展示时再转本地时区，避免夏令时歧义；二是 pageSize 不宜盲目调大，超过服务端上限会被截断或报错，建议从 100 起步；三是翻页时保持过滤条件一致，否则 total 会变化导致漏读或重复。若接口支持游标分页（cursor），优先使用游标而非页码，可避免数据插入导致的偏移问题。

调试建议：先用 API Key 快速验证端点与参数是否正确，确认无误后再切换到 OAuth 2.0 并收紧 scope，这样能把“认证问题”和“参数问题”分开定位。

安全提醒：client_secret 与 API Key 属于敏感凭证，禁止硬编码在前端或提交到代码仓库；应通过环境变量或密钥管理服务注入，并定期轮换。

把以上四部分串起来，一次完整的调用就是：确定 host 与 version → 选择认证方式获取凭证 → 构造带过滤与分页参数的 URL → 声明 JSON 格式 → 发送请求 → 依据状态码与 error.code 判读结果。掌握这条链路，后续的设备数据采集、告警订阅与能效分析才有稳定的接入基础。