1. 接口描述

接口请求域名: vssapi.ctyun.cn
默认接口请求频率限制：500次/秒。

查询设备信息。

2. 请求参数

参数	类型	是否必选	示例值	描述
Action	String	是	DescribeDevice	操作接口名，系统规定参数。
InProtocol	String	是	ehome	使用的接入协议。取值: ehome
DeviceId	String	是	32388487739092996	设备ID。
IncludeDeviceStats	Long	否	0	是否返回设备统计信息，默认0。取值：0(不返回), 1(返回)
IncludeDeviceDir	Long	否	0	是否返回目录信息，默认0。取值：0(不返回), 1(返回)

3. 返回参数

参数	类型	描述
DeviceId	String	设备ID。
GroupId	String	设备所属组ID。
ParentDeviceId	String	上级设备ID，比如摄像头所属的NVR设备ID。
DirId	String	设备所属目录ID。
GbId	String	设备国标ID。
DeviceType	String	设备类型。取值: ipc, nvr, platform
EhomeVersion	String	ehome版本。取值: 2.0, 4.0, 5.0
DeviceVendor	String	设备厂商。
DeviceName	String	设备名称。
Description	String	设备描述。
DeviceIp	String	设备IP。
DevicePort	Long	设备Port。
DeviceStatus	String	设备状态。取值：on(在线), off(离线), new(未注册)。
PullType	Long	是否启用自动拉流，默认继承组PullType，但如果设置了该字段，则会覆盖组下面的PullType值。取值：1, 2 取值为1，自动拉流，国标设备注册成功后自动启动拉流；取值为2，按需拉流，需要通过触发的方式启动拉流。
TransPriority	String	设备视频流优先传输协议，默认tcp。取值：tcp, udp。取值为tcp，如果设备支持tcp协议传输，设备进行视频邀约时优先使用tcp协议接入到vss服务中。取值为udp，设备进行视频邀约时优先使用udp协议接入到vss服务中。
ChannelSize	Long	设备通道数量，nvr设备时才需要填写。
CreateSubDevice	Long	是否自动创建子设备，默认1。取值：1(自动创建), 2(手动创建)
ChannelNum	Long	手动创建子设备时，需指定通道号
ChannelName	String	手动创建子设备时，需指定通道名称
MultiStreamSize	Long	主子码流数量，默认为1。取值: 1: 单码流（仅有一种码流） 2: 双码流（主、子码流） 3: 三码流（主、子、第三码流）
AutoStreamNum	Long	自动拉取第几个码流。 PullType取值为1，该字段为必选项。取值: 1: 主码流 2: 子码流 3: 第三码流
DeviceChannels	DeviceChannel[]	nvr设备通道列表。 ipc设备忽略该字段，nvr设备才返回。
DeviceStreams	DeviceStream[]	设备对应的流信息
DeviceStats	DeviceStats	设备统计信息。
DeviceDir	DeviceDir	设备目录。
DeviceLongitude	String	经度
DeviceLatitude	String	维度
GbRegion	String	国标地区编码
GbRegionLevel	Long	国标地区级别
CreatedTime	String	设备创建时间。
UpdatedTime	String	设备更新时间。
RequestId	String	唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

DeviceChannel

参数	类型	描述
ChannelNum	Long	通道号。
ChannelName	String	通道名称。
GbId	String	设备国标ID。
DeviceId	String	设备ID。
DeviceStatus	String	设备状态。取值：on(在线), off(离线), new(未注册)。
DeviceStreams	DeviceStream[]	设备对应的流信息
CreatedTime	String	子设备（通道）创建时间。
UpdatedTime	String	子设备（通道）更新时间。

DeviceStream

参数	类型	描述
StreamNum	Long	通道号。
StreamStatus	String	流状态。取值：on(在线), off(离线), failed(失败)。

DeviceStats

参数	类型	描述
ChannelSize	Long	通道数量。
OnlineChannels	Long	在线通道数量。
OffineChannels	Long	离线通道数量。
OnlineStreams	Long	在线流数量。
OfflineStreams	Long	离线流数量。
FailedStreams	Long	失败流数量。

DeviceDir

参数	类型	描述
DirId	String	目录ID。
DirName	String	目录名称。
Description	String	目录描述。
GroupId	String	目录所属组ID。
ParentDirId	String	上级目录ID。
CreatedTime	String	目录创建时间。
UpdatedTime	String	目录修改时间。

4. 示例

4.1 请求示例

https://vssapi.ctyun.cn/
?Action=DescribeDevice
&InProtocol=gb28181
&DeviceId=29942114322219022
&IncludeDeviceDir=1
&IncludeDeviceStats=1
&Version=2020-06-12
&AccessKeyId=O0G0BPBI2T9YUD3U****
&Signature=OMq1XDhZGNLkkkGl6VjMzADgk4w%3D
&SignatureMethod=HMAC-SHA1
&SignatureNonce=174345971
&SignatureVersion=1.0
&Timestamp=1599108494

4.2 返回示例

{
  "DeviceId": "29942114322219022",
  "GroupId": "748928498239799296",
  "ParentDeviceId": "-1",
  "DirId": "748928844311822336",
  "DeviceType": "nvr",
  "DeviceVendor": "",
  "DeviceName": "nvr2",
  "Description": "",
  "DeviceIp": "",
  "DevicePort": 0,
  "InProtocol": "gb28181",
  "UserName": "device",
  "UserPassword": "123456",
  "GbId": "34082400011188226858",
  "PullType": 1,
  "TransPriority": "tcp",
  "DeviceEnabled": 1,
  "DeviceStatus": "on",
  "StreamStatus": "",
  "SipTransType": "",
  "StreamTransType": "ps_rtp_udp",
  "CreateSubDevice": 1,
  "GbVersion": "2011",
  "DeviceChannels": [
    {
      "ChannelNum": 1,
      "ChannelName": "通道1",
      "GbId": "34082400011328367668",
      "DeviceId": "29942045602742287",
      "DeviceStatus": "on",
      "StreamStatus": "failed",
      "CreatedTime": "2020-08-31 09:43:55",
      "UpdatedTime": "2020-09-02 19:21:04"
    },
    {
      "ChannelNum": 2,
      "ChannelName": "通道2",
      "GbId": "34082400011328546061",
      "DeviceId": "29941979030749200",
      "DeviceStatus": "on",
      "StreamStatus": "on",
      "CreatedTime": "2020-08-31 09:43:56",
      "UpdatedTime": "2020-09-02 19:21:04"
    }
  ],
  "DeviceStats": {
    "ChannelSize": 2,
    "OnlineChannels": 2,
    "OfflineChannels": 0,
    "OnlineStreams": 1,
    "OfflineStreams": 0,
    "FailedStreams": 1
  },
  "DeviceDir": {
    "DirId": "748928844311822336",
    "DirName": "device",
    "Description": "",
    "GroupId": "748928498239799296",
    "ParentDirId": "0",
    "CreatedTime": "2020-08-28 15:35:51",
    "UpdatedTime": "2020-08-28 15:35:51"
  },
  "CreatedTime": "2020-08-31 09:43:55",
  "UpdatedTime": "2020-09-02 19:21:04",
  "RequestId": "436c7c0e49fa49db86e32f244091276b"
}

5. 错误码

ErrorCode	ErrorMessage

查询设备

最近更新时间：2025-11-21 07:44:44

1. 接口描述

2. 请求参数

3. 返回参数

DeviceChannel

DeviceStream

DeviceStats

DeviceDir

4. 示例

4.1 请求示例

4.2 返回示例

5. 错误码