设备 API

1. 获取已绑定设备

获取已绑定设备

获取指定智能体下所有已绑定的设备列表，包含设备的详细信息如MAC地址、连接状态、版本信息等。

GEThttps://xrobo.qiniu.com/xiaozhi/device/bind/{agentId}

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:GET

返回类型:application/json

请求参数

参数名类型必填位置说明

agentIdstring是-智能体ID，用于指定要查询设备的智能体

请求头

Header名类型必填说明

Authorizationstring是Bearer token，用户认证令牌

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "aa:bb:cc:dd:ee:ff",
      "userId": "user123",
      "macAddress": "aa:bb:cc:dd:ee:ff",
      "lastConnectedAt": "2024-01-15T10:30:00Z",
      "autoUpdate": 1,
      "board": "ESP32-S3",
      "alias": "客厅音箱",
      "agentId": "4057d21254664408a2f58200d7ba01e0",
      "appVersion": "1.2.3",
      "sort": 1,
      "updater": "user123",
      "updateDate": "2024-01-15T10:30:00Z",
      "creator": "user123",
      "createDate": "2024-01-10T08:00:00Z"
    }
  ]
}

状态码

0成功获取设备列表

401未授权，token无效或已过期

404智能体不存在

500服务器内部错误

2. 解绑设备

解绑设备

解除设备与用户账户的绑定关系。解绑后设备将无法接收智能体指令。

POSThttps://xrobo.qiniu.com/xiaozhi/device/unbind

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:POST

返回类型:application/json

请求参数

参数名类型必填位置说明

deviceIdstring是-要解绑的设备ID（通常是MAC地址）

请求头

Header名类型必填说明

Authorizationstring是Bearer token，用户认证令牌

Content-Typestring是application/json

请求示例

{
  "deviceId": "aa:bb:cc:dd:ee:ff"
}

响应示例

{
  "code": 0,
  "message": "设备解绑成功"
}

状态码

0解绑成功

3. 绑定设备

绑定设备

使用设备激活码将设备绑定到指定的智能体。绑定成功后设备可以接收该智能体的指令。

POSThttps://xrobo.qiniu.com/xiaozhi/device/bind/{agentId}/{deviceCode}

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:POST

返回类型:application/json

请求参数

参数名类型必填位置说明

agentIdstring是-智能体ID，设备将绑定到此智能体

deviceCodestring是-设备激活码，用于验证设备身份

请求头

Header名类型必填说明

Authorizationstring是Bearer token，用户认证令牌

响应示例

{
  "code": 0,
  "message": "设备绑定成功",
  "data": {
    "id": "aa:bb:cc:dd:ee:ff",
    "userId": "user123",
    "macAddress": "aa:bb:cc:dd:ee:ff",
    "lastConnectedAt": "2024-01-15T10:30:00Z",
    "autoUpdate": 1,
    "board": "ESP32-S3",
    "alias": "新设备",
    "agentId": "4057d21254664408a2f58200d7ba01e0",
    "appVersion": "1.2.3",
    "sort": 1,
    "updater": "user123",
    "updateDate": "2024-01-15T10:30:00Z",
    "creator": "user123",
    "createDate": "2024-01-15T10:30:00Z"
  }
}

状态码

0绑定成功

400设备激活码无效或已使用

401未授权，token无效或已过期

404智能体不存在

409设备已被绑定

500服务器内部错误

4. 批量导入设备（通过MAC地址绑定）

批量导入设备（通过MAC地址绑定）

通过MAC地址批量导入设备到指定智能体。支持同时导入多个设备，返回成功和失败的统计信息。

POSThttps://xrobo.qiniu.com/xiaozhi/device/preregister

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:POST

返回类型:application/json

请求参数

参数名类型必填位置说明

agent_idstring是-智能体ID，设备将关联到此智能体

mac_addressesarray是-MAC地址数组，要导入的设备MAC地址列表

serial_numbersarray是-序列号数组，设备序列号列表（可为空）

请求头

Header名类型必填说明

Authorizationstring是Bearer token，用户认证令牌

Content-Typestring是application/json

请求示例

{
  "agent_id": "4057d21254664408a2f58200d7ba01e0",
  "mac_addresses": [
    "F2:F1:A8:6A:C4:6B"
  ],
  "serial_numbers": []
}

响应示例

{
  "success_count": 1,
  "failed": []
}

 // 失败示例
{
  "success_count": 0,
  "failed": [
    {
      "value": "F2:F1:A8:6A:C4:6B",
      "reason": "已存在"
    }
  ]
}

状态码

0批量导入完成（可能部分失败）

设备实体结构

设备对象包含以下字段：

• id: 设备唯一标识符（通常是MAC地址）
• userId: 关联用户ID
• macAddress: 设备MAC地址
• lastConnectedAt: 最后连接时间（ISO 8601格式）
• autoUpdate: 自动更新开关（0关闭/1开启）
• board: 设备硬件型号
• alias: 设备别名
• agentId: 绑定的智能体ID
• appVersion: 固件版本号
• sort: 排序值
• updater: 更新者ID
• updateDate: 更新时间（ISO 8601格式）
• creator: 创建者ID
• createDate: 创建时间（ISO 8601格式）

认证说明

所有设备管理API都需要在请求头中包含有效的Bearer token：

Authorization: Bearer {token}