执行设备操作

向指定设备的指定继电器下发操作命令，支持 ON、OFF、JOG 三种动作。服务端最多同步等待 10 秒以获取设备执行确认，并在响应中的 data.status 直接给出当前命令状态。

限流

维度	规则	触发后行为
同一应用	60 秒内最多 600 次继电器控制请求	返回 429 RATE_LIMITED
同一设备	10 秒内最多 10 次继电器控制请求	返回 429 RATE_LIMITED
同一继电器冷却	每次操作后冷却 3 秒	返回 429 RATE_LIMITED，并带 Retry-After

同步等待

• 首次请求会最多等待 10 秒
• 10 秒内拿到终态时，返回 SUCCESS、FAILED 或 TIMEOUT
• 如果调用方复用同一个 Idempotency-Key 重试，而原请求仍在等待设备确认，则可能返回 SENT
• TIMEOUT 表示在等待窗口内没有拿到最终确认，应按"未确认成功"处理

端点

POST /wlte/v1/devices/{deviceId}/relays/{index}/commands

权限要求

Scope	必须	说明
device:control	是	对指定设备继电器下发控制命令

请求

完整地址：

POST {baseUrl}/wlte/v1/devices/{deviceId}/relays/{index}/commands

请求头：

Authorization: Bearer {accessToken}
Content-Type: application/json
Accept: application/json
Idempotency-Key: <调用方生成的唯一字符串>

路径参数：

参数	类型	必填	规则
deviceId	string	是	不能为空
index	integer	是	正整数，从 1 开始

请求体：

{
  "action": "JOG"
}

字段规则：

字段	类型	必填	规则
action	string	是	只允许 ON、OFF、JOG

动作说明：

动作	说明
ON	继电器保持接通
OFF	继电器保持断开
JOG	点动：继电器短暂闭合后自动断开，时长由设备持久化配置决定

Idempotency-Key

Idempotency-Key 是必填请求头，由调用方生成的唯一字符串，用于标识一次操作意图。服务端通过它防止网络重试或应用层重试导致同一命令被重复执行。

何时生成新 key，何时复用

场景	操作
发出一次新的继电器操作（无论之前是否有过操作）	生成新 key
发出请求后网络超时，未收到任何响应	复用原 key 重试
收到 429 RATE_LIMITED 需要重试继电器命令	复用原 key 重试
用户主动发起第二次独立操作（例如再次开关继电器）	生成新 key

格式要求

• 长度：1 到 128 个字符
• 字符集：字母、数字、-、_
• 推荐使用 UUID v4，例如 550e8400-e29b-41d4-a716-446655440000

重复请求行为

• 同一客户端、同一路径、相同 key + 相同请求体：返回 202 Accepted 和原始命令 id，不会重复执行
• 相同 key 但请求体不同：返回 409 IDEMPOTENCY_CONFLICT
• 服务端至少保留 48 小时的幂等记录；超过有效期后相同 key 会被视为新请求

网络超时处理流程

1. 发出请求，网络层超时，未收到任何响应
2. 使用同一个 Idempotency-Key 重新发送相同请求
3. 服务端识别重复请求，返回该命令当前状态（SENT、SUCCESS、FAILED 或 TIMEOUT）
4. 如仍需确认最终结果，用命令 id 调用 查询命令结果

成功响应

HTTP 状态码：

202 Accepted

响应体（设备已确认成功）：

{
  "code": "COMMAND_ACCEPTED",
  "message": "Command accepted.",
  "requestId": "req_001",
  "data": {
    "id": "cmd_001",
    "deviceId": "abc123456789",
    "relayIndex": 1,
    "action": "JOG",
    "status": "SUCCESS",
    "createdAt": "2026-04-29T00:00:00Z"
  }
}

响应体（等待窗口超时）：

{
  "code": "COMMAND_ACCEPTED",
  "message": "Command accepted.",
  "requestId": "req_001",
  "data": {
    "id": "cmd_001",
    "deviceId": "abc123456789",
    "relayIndex": 1,
    "action": "JOG",
    "status": "TIMEOUT",
    "createdAt": "2026-04-29T00:00:00Z"
  }
}

状态说明

• SENT：命令已被接受，但当前仍在等待设备最终确认；该状态通常只会出现在复用同一个 Idempotency-Key 的重复请求或后续查询中
• SUCCESS：设备已确认执行成功
• FAILED：设备返回失败，或平台确认命令未成功完成
• TIMEOUT：在等待窗口内没有拿到最终确认，应按未确认成功处理

响应 data 结构

字段	类型	必填	说明
id	string	是	命令唯一标识；需持久化，后续用于查询命令结果
deviceId	string	是	设备唯一标识
relayIndex	integer	是	继电器序号，从 1 开始
action	string	是	命令动作，枚举：ON、OFF、JOG
status	string	是	命令状态，枚举：SENT、SUCCESS、FAILED、TIMEOUT
createdAt	string	是	命令创建时间，RFC3339 UTC

错误响应

可能返回：

• 400 INVALID_REQUEST
• 401 AUTH_REQUIRED
• 401 AUTH_INVALID
• 401 AUTH_EXPIRED
• 403 AUTH_SCOPE_DENIED
• 404 DEVICE_NOT_FOUND
• 409 IDEMPOTENCY_CONFLICT
• 422 COMMAND_REJECTED
• 422 DEVICE_OFFLINE
• 429 RATE_LIMITED
• 503 GATEWAY_UNAVAILABLE
• 500 INTERNAL_ERROR

429 RATE_LIMITED 响应体

触发限流时，响应体会携带 data 字段，说明触发的具体限流策略：

{
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "requestId": "req_001",
  "data": {
    "retryAfterSeconds": 3
  }
}

retryAfterSeconds 与 Retry-After 响应头的值相同，单位为秒。