查询设备列表
最近更新时间：2025-11-21 07:44:44
1. 接口描述
接口请求域名: vssapi.ctyun.cn
默认接口请求频率限制：500次/秒。
查询设备列表。
2. 请求参数
| 参数 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|
| Action | String | 是 | DescribeDevices | 操作接口名，系统规定参数。 |
| InProtocol | String | 否 | gb28181 | 使用的接入协议。 取值: gb28181 虚拟业务组vgroup时，可为空 |
| GroupId | String | 是 | 32388487739092994 | 根据设备所属组ID查询。 |
| ParentDeviceId | String | 否 | 32388487739092995 | 根据设备所属上级设备ID查询。 |
| DirId | String | 否 | 897098424844288 | 根据设备所属目录ID查询。 |
| DeviceVendor | String | 否 | 海康 | 根据设备厂商查询。 |
| DeviceName | String | 否 | 高空抛物摄像头 | 根据设备名称查询。 |
| DeviceType | String | 否 | ipc | 根据设备类型查询。 取值: ipc,nvr,platform |
| DeviceStatus | String | 否 | on | 根据设备状态查询。 取值：on(在线), off(离线), new(未注册)。 |
| StreamStatus | String | 否 | on | 根据流状态查询。 取值：on(在线), off(离线), failed(失败)。 |
| SortBy | String | 否 | CreatedTime | 选择按一个字段排序，可选值为： - DeviceID - CreatedTime - UpdatedTime 默认为CreatedTime，按照创建时间排序。 |
| SortDirection | String | 否 | asc | 排序方式，默认升序。 取值：asc(升序), desc(降序)。 |
| PageNum | Long | 否 | 1 | 第几个分页，默认为1。 |
| PageSize | Long | 否 | 20 | 分页大小，默认为10。 取值范围为1～1000 |
| IncludeDeviceStats | Long | 否 | 0 | 是否返回设备统计信息，默认0。 取值：0(不返回), 1(返回) |
| IncludeDeviceDir | Long | 否 | 0 | 是否返回目录信息，默认0。 取值：0(不返回), 1(返回) |
3. 返回参数
| 参数 | 类型 | 描述 |
|---|---|---|
| PageNum | Long | 第几个分页。 |
| PageSize | Long | 分页大小。 |
| TotalPage | Long | 分页总数。 |
| TotalNum | Long | 设备总数。 |
| Devices | Device[] | 设备列表。 |
| RequestId | String | 唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。 |
| DirStats | DirStats | 目录统计信息。 |
| Actions | String[] | 操作集合。 |
Device
| 参数 | 类型 | 描述 |
|---|---|---|
| DeviceId | String | 设备ID。 |
| GroupId | String | 设备所属组ID。 |
| ParentDeviceId | String | 上级设备ID，比如摄像头所属的NVR设备ID。 |
| DirId | String | 设备所属目录ID。 |
| DeviceType | String | 设备类型。取值: ipc,nvr,platform |
| GbVersion | String | 国标版本。 取值: 2011, 2016 |
| DeviceVendor | String | 设备厂商。 |
| DeviceName | String | 设备名称。 |
| Description | String | 设备描述。 |
| DeviceIp | String | 设备IP。 |
| DevicePort | Long | 设备Port。 |
| InProtocol | String | 设备使用的接入协议。 取值: gb28181~~, rtmp, onvif, rtsp~~ |
| UserName | String | 设备用户名，在创建GB28181凭证时生成。 |
| UserPassword | String | 设备密码，在创建GB28181凭证时生成。 |
| GbId | String | 设备国标ID。 |
| PullType | Long | 是否启用自动拉流。 仅gb28181组支持该字段。 取值：1, 2 取值为1，自动拉流，国标设备注册成功后自动启动拉流； 取值为2，按需拉流，需要通过触发的方式启动拉流。 |
| TransPriority | String | 设备视频流优先传输协议，默认tcp。 取值：tcp, udp。 取值为tcp，如果设备支持tcp协议传输，设备进行视频邀约时优先使用tcp协议接入到vss服务中。 取值为udp，设备进行视频邀约时优先使用udp协议接入到vss服务中。 |
| DeviceEnabled | Long | 设备是否启用。 取值：0(停用), 1(启用) |
| DeviceStatus | String | 设备状态。 取值：on(在线), off(离线), new(未注册)。 |
| StreamStatus | String | 流状态。 取值：on(在线), off(离线), failed(失败)。 |
| SipTransType | String | 信令传输类型。 取值：tcp, udp |
| StreamTransType | String | 流传输类型。 ps_rtp_udp: PS over RTP UDP ps_rtp_tcp: PS over RTP TCP h264_rtp_udp: H264 over RTP UDP h264_rtp_tcp: H264 over RTP TCP |
| CreateSubDevice | Long | 是否自动创建子设备。 取值：1(自动创建), 2(手动创建) |
| DeviceStats | DeviceStats | 设备统计信息。 |
| DeviceDir | DeviceDir | 设备目录。 |
| SerialNumber | String | 设备SN码。 |
| DeviceModel | String | 设备型号。 |
| CreatedTime | String | 设备创建时间。 |
| UpdatedTime | String | 设备更新时间。 |
| RecordStatus | Int | 录制状态。 |
| RecordTaskId | String | 录制任务ID。 |
| GbRegion | String | 设备区域编码。 |
| GbRegionLevel | String | 设备区域级别。 |
| PushType | Int | 是否启用自动激活推流地址。 |
| InType | String | 视频流接入方式。 |
| PushUrl | String | 推流地址。 |
| PullUrl | String | 拉流地址。 |
| Tags | String | 标签。 |
| MultiStreamSize | Int | 主子码流数量。 |
| AutoStreamNum | Int | 自动拉取第几个码流。 |
| DeviceSn | String | 设备ID序列号。 |
| DeviceFirmware | String | 设备固件号。 |
| DeviceHardware | String | 设备硬件号。 |
| DevicePosition | String | 设备位置。 |
| DevicePubIp | String | 设备公网出口Ip。 |
| DevicePubPort | Int | 设备公网出口Port。 |
| EhomeVersion | String | ehome版本。 |
| ChannelSize | Int | 通道数量。 |
| ChannelNum | Int | 通道号。 |
| ChannelName | String | 通道名称。 |
| DeviceStreams | string[] | 设备视频流信息。 |
| DeviceLongitude | String | 设备经度。 |
| DeviceLatitude | String | 设备纬度。 |
| DeviceDomain | String | 设备域名。 |
| EnableDomain | Int | 是否启用域名。 |
DeviceStats
| 参数 | 类型 | 描述 |
|---|---|---|
| ChannelSize | Long | 通道数量。 |
| OnlineChannels | Long | 在线通道数量。 |
| OfflineChannels | Long | 离线通道数量。 |
| OnlineStreams | Long | 在线流数量。 |
| OfflineStreams | Long | 离线流数量。 |
| FailedStreams | Long | 失败流数量。 |
| MaxChannelSize | Long | 最大通道数量。 |
DeviceDir
| 参数 | 类型 | 描述 |
|---|---|---|
| DirId | String | 目录ID。 |
| DirName | String | 目录名称。 |
| Description | String | 目录描述。 |
| GroupId | String | 目录所属组ID。 |
| ParentDirId | String | 上级目录ID。 |
| CreatedTime | String | 目录创建时间。 |
| UpdatedTime | String | 目录修改时间。 |
DirStats
| 参数 | 类型 | 描述 |
|---|---|---|
| DeviceSize | String | 设备数量 |
| IpcSize | String | IPC设备数量 |
| NvrSize | String | NVR设备数量 |
| PlatformSize | String | 平台设备数量 |
4. 示例
4.1 请求示例
https://vssapi.ctyun.cn/
?Action=DescribeDevices
&InProtocol=gb28181
&GroupId=883904285310976
&IncludeDeviceDir=1
&IncludeDeviceStats=1
&Version=2020-06-12
&AccessKeyId=O0G0BPBI2T9YUD3U****
&Signature=b5Gv5U2hlTHgeEaKE9KgVoo6DWw%3D
&SignatureMethod=HMAC-SHA1
&SignatureNonce=1578406
&SignatureVersion=1.0
&Timestamp=1599113545
4.2 返回示例
{
"PageNum": 1,
"PageSize": 20,
"TotalPage": 1,
"TotalNum": 3,
"Devices": [
{
"DeviceId": "29942077814997590",
"GroupId": "883904285310976",
"ParentDeviceId": "29942103584801365",
"DirId": "-1",
"DeviceType": "ipc",
"DeviceVendor": "",
"DeviceName": "test-nvr",
"Description": "",
"DeviceIp": "",
"DevicePort": 0,
"InProtocol": "",
"UserName": "user",
"UserPassword": "user",
"GbId": "34082400011328566275",
"PullType": 2,
"TransPriority": "tcp",
"DeviceEnabled": 1,
"DeviceStatus": "new",
"StreamStatus": "",
"SipTransType": "",
"StreamTransType": "",
"CreateSubDevice": 1,
"GbVersion": "2011",
"DeviceStats": {
"ChannelSize": 1,
"OnlineChannels": 0,
"OfflineChannels": 0,
"OnlineStreams": 0,
"OfflineStreams": 0,
"FailedStreams": 0
},
"DeviceDir": {
"DirId": "0",
"DirName": "",
"Description": "",
"GroupId": "0",
"ParentDirId": "0",
"CreatedTime": "0001-01-01 00:00:00",
"UpdatedTime": "0001-01-01 00:00:00"
},
"CreatedTime": "2020-09-02 17:44:12",
"UpdatedTime": "2020-09-02 18:14:21",
"RequestId": "3247575e6e1044668962f5a464fa3885"
},
{
"DeviceId": "29942071372546647",
"GroupId": "883904285310976",
"ParentDeviceId": "29942103584801365",
"DirId": "-1",
"DeviceType": "ipc",
"DeviceVendor": "",
"DeviceName": "test-nvr",
"Description": "",
"DeviceIp": "",
"DevicePort": 0,
"InProtocol": "",
"UserName": "user",
"UserPassword": "user",
"GbId": "34082400011328199910",
"PullType": 2,
"TransPriority": "tcp",
"DeviceEnabled": 1,
"DeviceStatus": "new",
"StreamStatus": "",
"SipTransType": "",
"StreamTransType": "",
"CreateSubDevice": 1,
"GbVersion": "2011",
"DeviceStats": {
"ChannelSize": 1,
"OnlineChannels": 0,
"OfflineChannels": 0,
"OnlineStreams": 0,
"OfflineStreams": 0,
"FailedStreams": 0
},
"DeviceDir": {
"DirId": "0",
"DirName": "",
"Description": "",
"GroupId": "0",
"ParentDirId": "0",
"CreatedTime": "0001-01-01 00:00:00",
"UpdatedTime": "0001-01-01 00:00:00"
},
"CreatedTime": "2020-09-02 17:44:12",
"UpdatedTime": "2020-09-02 18:14:21",
"RequestId": "3247575e6e1044668962f5a464fa3885"
},
{
"DeviceId": "29942103584801365",
"GroupId": "883904285310976",
"ParentDeviceId": "-1",
"DirId": "-1",
"DeviceType": "nvr",
"DeviceVendor": "",
"DeviceName": "test-nvr",
"Description": "",
"DeviceIp": "",
"DevicePort": 0,
"InProtocol": "",
"UserName": "user",
"UserPassword": "user",
"GbId": "34082400011188419252",
"PullType": 2,
"TransPriority": "tcp",
"DeviceEnabled": 1,
"DeviceStatus": "new",
"StreamStatus": "",
"SipTransType": "",
"StreamTransType": "",
"CreateSubDevice": 1,
"GbVersion": "2011",
"DeviceStats": {
"ChannelSize": 2,
"OnlineChannels": 0,
"OfflineChannels": 0,
"OnlineStreams": 0,
"OfflineStreams": 0,
"FailedStreams": 0
},
"DeviceDir": {
"DirId": "0",
"DirName": "",
"Description": "",
"GroupId": "0",
"ParentDirId": "0",
"CreatedTime": "0001-01-01 00:00:00",
"UpdatedTime": "0001-01-01 00:00:00"
},
"CreatedTime": "2020-09-02 17:44:12",
"UpdatedTime": "2020-09-02 18:14:21",
"RequestId": "3247575e6e1044668962f5a464fa3885"
}
],
"RequestId": "3247575e6e1044668962f5a464fa3885"
}
5. 错误码
| ErrorCode | ErrorMessage |
|---|---|
本页目录：