控制单路继电器（即将停用）

兼容接口

此接口用于兼容已有集成，将在未来版本关闭。新集成请使用 执行继电器命令，它使用统一的数组结构，并支持一次控制一路或多路继电器。

每次调用仍作为一条独立设备命令计入操作频率。需要同时控制多路时，使用推荐接口合并发送。

端点

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	是	设备 ID
index	integer	是	继电器序号，从 1 开始

{
  "action": "ON"
}

curl 示例：

curl --request POST '{baseUrl}/wlte/v1/devices/{deviceId}/relays/{index}/commands' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: <调用方生成的唯一字符串>' \
  --data '{
    "action": "ON"
  }'

action 支持 ON、OFF 和 JOG。Idempotency-Key 的使用规则与推荐接口一致。

成功响应

{
  "code": "COMMAND_ACCEPTED",
  "message": "Command accepted.",
  "requestId": "req_001",
  "data": {
    "id": "cmd_001",
    "deviceId": "abc123456789",
    "relayIndex": 1,
    "action": "ON",
    "status": "SUCCESS",
    "createdAt": "2026-07-15T08:30:00Z"
  }
}

响应包含 Deprecation: true，并通过 Link 指向推荐的多路控制端点。迁移时将路径中的 index 和请求体中的 action 合并为：

{
  "relays": [
    { "index": 1, "action": "ON" }
  ]
}

需要稍后确认结果时，使用 data.id 调用 查询命令结果。

错误响应

可能返回 400 INVALID_REQUEST、401 AUTH_REQUIRED、401 AUTH_INVALID、401 AUTH_EXPIRED、403 AUTH_SCOPE_DENIED、404 DEVICE_NOT_FOUND、409 DEVICE_BUSY、409 IDEMPOTENCY_CONFLICT、422 COMMAND_REJECTED、422 DEVICE_OFFLINE、429 RATE_LIMITED、503 GATEWAY_UNAVAILABLE 或 500 INTERNAL_ERROR。