查询设备绑定的有效角色
查询范围仅限当前 API Key 已关联且处于上架状态的硬件渠道。
请求信息
请求 URI
GET https://lg.jimitu.top/api/open/devices/character请求头参数
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer {API Key}，接口鉴权，所有请求均需携带 |
Content-Type | 否 | 仅 POST/PUT 携带 JSON 请求体时需要，值为 application/json |
请求查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| device_id | string | 是 | 设备 ID |
| channel_id | integer | 否 | 渠道 ID；同一令牌范围内存在重复设备 ID 时用于消歧 |
| product_key | string | 否 | 产品型号 ID；同一设备 ID 对应多个产品型号时用于消歧 |
请求示例
curl -X GET "https://lg.jimitu.top/api/open/devices/character?device_id=<device_id>&channel_id=100" \
-H "Authorization: Bearer <your_api_key>"响应信息
响应体示例
{
"success": true,
"data": {
"device_id": "123456",
"product_key": "...",
"channel_id": 100,
"binding_id": 999,
"character_id": 555,
"template_publishing_id": 1,
"external_user_id": "<user_id>",
"external_user_nickname": "..."
}
}响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| device_id | string | 设备 ID |
| product_key | string | 产品型号 ID |
| channel_id | integer | 渠道 ID |
| binding_id | integer | 绑定记录 ID |
| character_id | integer | 有效角色实例 ID |
| template_publishing_id | integer | 关联上架 ID |
| external_user_id | string | 外部用户 ID（未绑定时为空串） |
| external_user_nickname | string | 外部用户昵称（未绑定时为空串） |
注意
设备未绑定 APP 用户时，external_user_id 和 external_user_nickname 均返回空字符串。
错误码
错误码
| 场景 | error_code | HTTP |
|---|---|---|
| 缺少设备 ID | DEVICE_ID_REQUIRED | 400 |
| channel_id 格式错误 | INVALID_CHANNEL_ID | 400 |
| 授权范围内没有有效设备角色绑定 | DEVICE_CHARACTER_NOT_FOUND | 404 |
| 授权范围内有多个同 ID 设备 | DEVICE_ID_AMBIGUOUS | 409 |