设备列表

分页查询客户端部门范围内可见的设备。

GET/openapi/v1/device/list

只读幂等键：无需所需权限 device:list授权说明 ↗

查询参数

字段	类型	必填	说明
`page`	integer	否	页码，从 1 开始；省略时默认为 1，显式空值会被拒绝。默认 1 · int32 · ≥ 1
`pageSize`	integer	否	每页条数，最大 100；省略时默认为 20，显式空值会被拒绝。默认 20 · int32 · ≥ 1 · ≤ 100
`keyword`	string	否	搜索关键字，最长 100 个字符；空值合法。最长 100
`status`	string	否	状态筛选，可选 online、offline 或 unknown；显式空值会被拒绝。 "online" · "offline" · "unknown"
`manufacturer`	string	否	制造商精确匹配；省略时不按制造商筛选。最长 100
`model`	string	否	设备型号精确匹配；省略时不按型号筛选。最长 100
`transport`	string	否	SIP 信令传输方式，支持 UDP 或 TCP。 "UDP" · "TCP"
`protocolVersion`	string	否	设备当前生效的国标协议版本：2016 或 2022。 "2016" · "2022"
`sort`	string	否	排序字段，仅接受下方枚举中的字段名。 "deviceId" · "name" · "status" · "registerTime" · "keepaliveTime" · "createdAt"
`order`	string	否	排序方向：asc 为升序，desc 为降序。 "asc" · "desc"

公共认证 HMAC-SHA256 · 5 个签名请求头

签名在服务端计算。时间偏差不超过 300 秒，每次请求使用新的 nonce。查看认证规则 ↗

字段	类型	必填	说明
`X-UVP-Sign-Version`	string	是	签名版本，当前仅接受 1。 "1"
`X-UVP-Access-Key`	string	是	客户端访问密钥（AK），用于标识调用方；对应密钥（SK）始终保留在服务端。格式 ^uvp_[0-9a-f]{32}$
`X-UVP-Timestamp`	string	是	Unix 秒级时间戳，与服务端时间偏差不得超过 300 秒。格式 ^(0\|[1-9][0-9]{0,18})$
`X-UVP-Nonce`	string	是	单次请求随机串，32 位小写十六进制；重复值或逗号拼接的值会被拒绝。格式 ^[0-9a-f]{32}$
`X-UVP-Signature`	string	是	对规范请求计算的 HMAC-SHA256 签名，小写十六进制共 64 位。格式 ^[0-9a-f]{64}$

调用示例

GET /openapi/v1/device/list?page=1&pageSize=20 HTTP/1.1
Host: <你的 API 服务域名>
X-UVP-Sign-Version: 1
X-UVP-Access-Key: <AK>
X-UVP-Timestamp: <Unix 秒级时间戳>
X-UVP-Nonce: <32 位随机十六进制>
X-UVP-Signature: <服务端计算的 HMAC-SHA256>

以上为请求结构。切换语言查看完整的服务端签名与调用代码。

返回结果

HTTP 状态

设备列表返回结果

字段名中的点号表示对象层级，[] 表示数组中的每一项。

字段	类型	必返	说明
`code`	string	是	业务结果码；成功为 OK。 "OK"
`message`	string	是	结果说明；成功为 success。 "success"
`requestId`	string	是	平台生成的请求追踪标识。
`data`	object	是	不接受额外字段
`data.items`	object[]	是	当前页的设备列表。
`data.items[].deviceId`	string	是	设备国标编码，20 位数字字符串。格式 ^[0-9]{20}$
`data.items[].name`	string	是	设备上报的名称；未上报时为空字符串。
`data.items[].alias`	string	是	平台配置的别名；未设置时为空字符串。
`data.items[].manufacturer`	string	是	设备上报的厂商；未上报时为空字符串。
`data.items[].model`	string	是	设备上报的型号；未上报时为空字符串。
`data.items[].status`	string	是	平台记录的在线状态：online 在线，offline 离线，unknown 状态未知。 "online" · "offline" · "unknown"
`data.items[].firmware`	string	是	设备上报的固件版本；未上报时为空字符串。
`data.items[].transport`	string	是	设备 SIP 信令传输方式，通常为 UDP 或 TCP；未知时为空字符串。
`data.items[].ip`	string	是	平台记录的设备 SIP 来源 IP 地址；未知时为空字符串。
`data.items[].port`	integer	是	平台记录的设备 SIP 来源端口；未知时为 0。 int32
`data.items[].registerTime`	string \| null	是	最近一次注册成功时间。未知或尚未发生时返回 null。 date-time
`data.items[].registerExpireAt`	string \| null	是	当前注册的到期时间。未知或尚未发生时返回 null。 date-time
`data.items[].keepaliveTime`	string \| null	是	最近一次收到设备心跳的时间。未知或尚未发生时返回 null。 date-time
`data.items[].keepaliveInterval`	integer	是	设备期望心跳周期，单位秒；0 表示尚无有效记录。 int32
`data.items[].expires`	integer	是	设备注册有效期，单位秒；0 表示尚无有效记录。 int32
`data.items[].offlineAt`	string \| null	是	最近一次被平台判定离线的时间。未知或尚未发生时返回 null。 date-time
`data.items[].channelCount`	integer	是	当前设备下对本客户端可见的通道总数；仅统计与设备同归属部门、未删除且设备与通道编码链唯一的通道。 int64 · ≥ 0
`data.items[].onlineChannelCount`	integer	是	可见通道中在线的数量；统计口径与 channelCount 一致，在线状态为 online。 int64 · ≥ 0
`data.items[].reportedVersion`	string	是	设备最近一次上报的原始协议版本声明，通常为 2016 或 2022；尚未声明时为空字符串。
`data.items[].effectiveVersion`	string	是	平台当前实际采用的协议版本，通常为 2016 或 2022；历史记录缺失时可能为空字符串。
`data.items[].effectiveVersionSource`	string	是	当前协议版本的来源：register 注册声明、override 人工覆盖、history 历史事实、default 平台默认；未记录时为空字符串。
`data.items[].effectiveVersionAt`	string \| null	是	当前生效协议版本最近一次确认或更新时间。未知或尚未发生时返回 null。 date-time
`data.items[].protocolOverride`	string	是	平台配置的协议版本覆盖策略：auto 自动、2016 或 2022 固定版本；历史记录缺失时可能为空字符串。
`data.items[].subscribeCapability`	string	是	目录订阅状态：unknown 尚未确认、subscribed 已订阅、fallback 已降级为轮询；历史记录缺失时可能为空字符串。 "" · "unknown" · "subscribed" · "fallback"
`data.items[].subscribeLastTest`	string \| null	是	最近一次尝试发送目录订阅的时间。未知或尚未发生时返回 null。 date-time
`data.items[].subscribeExpiresAt`	string \| null	是	当前目录订阅的到期时间。未知或尚未发生时返回 null。 date-time
`data.items[].reportedCharset`	string	是	设备最近一次 XML 报文声明的原始字符集；未声明或尚无报文时为空字符串。
`data.items[].wireCharset`	string	是	平台实际判定用于解码设备报文的字符集；尚无报文时为空字符串。
`data.items[].reportedCharsetAt`	string \| null	是	最近一次字符集事实确认时间。未知或尚未发生时返回 null。 date-time
`data.items[].createdAt`	string \| null	是	平台设备记录创建时间。未知或尚未发生时返回 null。 date-time
`data.items[].updatedAt`	string \| null	是	平台设备记录最近更新时间。未知或尚未发生时返回 null。 date-time
`data.page`	integer	是	当前页码。 ≥ 1
`data.pageSize`	integer	是	每页条数。 ≥ 1 · ≤ 100
`data.total`	integer	是	满足条件的设备总数。 int64 · ≥ 0

响应头

字段	类型	必填	说明
`Cache-Control`	string	是	"no-store"

响应示例

{
  "code": "OK",
  "message": "success",
  "requestId": "req_20261109_001",
  "data": {
    "items": [
      {
        "deviceId": "34020000002000000001",
        "name": "门店视频设备",
        "alias": "一楼门店",
        "manufacturer": "示例厂商",
        "model": "IPC-28181",
        "status": "online",
        "firmware": "V1.0.0",
        "transport": "TCP",
        "ip": "192.0.2.10",
        "port": 5060,
        "registerTime": "2026-11-09T08:00:00Z",
        "registerExpireAt": "2026-11-09T09:00:00Z",
        "keepaliveTime": "2026-11-09T08:05:00Z",
        "keepaliveInterval": 60,
        "expires": 3600,
        "offlineAt": null,
        "channelCount": 2,
        "onlineChannelCount": 1,
        "reportedVersion": "2022",
        "effectiveVersion": "2022",
        "effectiveVersionSource": "register",
        "effectiveVersionAt": "2026-11-09T08:00:00Z",
        "protocolOverride": "auto",
        "subscribeCapability": "subscribed",
        "subscribeLastTest": "2026-11-09T08:00:00Z",
        "subscribeExpiresAt": "2026-11-09T09:00:00Z",
        "reportedCharset": "GB18030",
        "wireCharset": "GB18030",
        "reportedCharsetAt": "2026-11-09T08:00:00Z",
        "createdAt": "2026-11-01T08:00:00Z",
        "updatedAt": "2026-11-09T08:05:00Z"
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

示例用于说明字段结构，实际结果以接口返回为准。

状态与错误

错误处理与重试约定 ↗

listDevicesOpenAPI 3.0.3 · v1.0.0