执行继电器命令

控制设备的一路或多路继电器。单路控制和多路控制使用同一个端点，单路控制时 relays 只包含一个元素。

同一请求中的多路操作作为一条设备命令发送，并只占用一次设备操作额度。不要将同一批变更拆成多个连续请求。

端点

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

权限要求

Scope	必须	说明
device:control	是	控制指定设备的继电器

请求

POST {baseUrl}/wlte/v1/devices/{deviceId}/relays/commands
Authorization: Bearer {accessToken}
Content-Type: application/json
Accept: application/json
Idempotency-Key: <调用方生成的唯一字符串>

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

字段	类型	必填	说明
relays	array	是	非空继电器操作列表
relays[].index	integer	是	继电器序号，从 1 开始；同一请求内不能重复
relays[].action	string	是	ON、OFF 或 JOG

动作说明：

动作	说明
ON	保持接通
OFF	保持断开
JOG	短暂接通后自动断开，持续时长使用设备保存的点动配置

请求中的继电器序号必须在设备能力范围内。可通过 查询设备类型定义列表 获取继电器数量和支持动作。

Idempotency-Key

Idempotency-Key 必填，用于标识一次操作意图。

场景	Key 使用方式
新的用户操作	生成新 key
网络超时，未收到响应	使用原 key 重试相同请求
收到 429 RATE_LIMITED 后重试同一操作	等待后使用原 key
设备、继电器列表或动作发生变化	生成新 key

相同 key 配相同请求不会重复下发；相同 key 配不同请求会返回 409 IDEMPOTENCY_CONFLICT。幂等记录保留约 48 小时。

成功响应

HTTP 状态码：

202 Accepted

{
  "code": "COMMAND_ACCEPTED",
  "message": "Command accepted.",
  "requestId": "req_001",
  "data": {
    "command": {
      "id": "cmd_001",
      "deviceId": "abc123456789",
      "operation": "device.relay.set",
      "status": "SUCCESS",
      "params": {
        "relays": [
          { "index": 1, "action": "ON" },
          { "index": 2, "action": "OFF" }
        ]
      },
      "createdAt": "2026-07-15T08:30:00Z"
    },
    "state": {
      "deviceId": "abc123456789",
      "status": "ONLINE",
      "peripherals": {
        "relays": [
          { "index": 1, "on": true },
          { "index": 2, "on": false }
        ],
        "digitalInputs": [
          { "index": 1, "active": false }
        ],
        "analogInputs": [],
        "sensors": []
      },
      "stateUpdatedAt": "2026-07-15T08:30:00Z"
    }
  }
}

字段	类型	必填	说明
data.command	object	是	命令对象
data.command.id	string	是	命令 ID，用于查询命令结果
data.command.operation	string	是	固定为 device.relay.set
data.command.params.relays	array	是	规范化后的操作列表
data.command.status	string	是	SENT、SUCCESS、FAILED 或 TIMEOUT
data.command.createdAt	string	是	命令创建时间，RFC3339 UTC
data.state	object	否	设备确认包同时携带的最新运行状态
data.state.peripherals	object	否	可能同时包含继电器、数字输入、模拟量和传感器状态

state 只在设备响应包含可用状态时返回。它不是为了补齐字段而触发的第二次设备刷新。

状态说明

• SENT：原命令仍在等待设备确认，通常出现在相同幂等键的重复请求中。
• SUCCESS：设备已确认执行。
• FAILED：平台已确认命令未成功完成。
• TIMEOUT：等待窗口内没有最终确认，应按未确认成功处理。

需要稍后确认状态时，使用 data.command.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。