# 设备、通道、流与统一资源接口

这一层把不同接入方式归一为设备、通道和流。做业务集成时优先调用统一通道与协议视图；只有协议特有能力才进入 GB28181 或 ONVIF 专页。

本页覆盖 **69** 个接口。每一行都回答五件事：接口地址、它做什么、何时调用、如何确认完成、谁可以调用。参数字段的精确定义以同版本 OpenAPI 为准。

> “业务接口”可以由 WebUI 或第三方系统按权限调用；“管理员接口”需要后台管理员；“内部接口/内部回调”只允许产品组件之间使用。

## 视频通道与流

| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/channels` | 查询视频通道列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | page、pageSize、mediaServerId、nodeId、protocol、vhost、app、stream、streamId、deviceId、deviceChannelId、enabled、autoVideo、autoRecord、noPlayerBreak、hasAudio、hasPtz、isShareChannel、desiredState、actualState、sourceUrl、keyword |
| `POST /api/v2/channels` | 创建视频通道。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | SaveVideoChannelRequest |
| `DELETE /api/v2/channels/{channelId}` | 删除视频通道。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | channelId（必填） |
| `GET /api/v2/channels/{channelId}` | 查看视频通道。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | channelId（必填） |
| `PUT /api/v2/channels/{channelId}` | 更新视频通道。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | channelId（必填）、SaveVideoChannelRequest |
| `POST /api/v2/channels/{channelId}/activate` | 激活待接入视频通道。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`channels.manage` | channelId（必填）、ActivateVideoChannelRequest |
| `POST /api/v2/channels/{channelId}/pause` | 人工暂停视频通道自动恢复。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | channelId（必填） |
| `POST /api/v2/channels/{channelId}/ptz` | 控制视频通道 云台动作。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`devices.control` | channelId（必填）、VideoChannelPtzRequest |
| `GET /api/v2/channels/{channelId}/ptz/capabilities` | 查看视频通道 云台动作 能力。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | channelId（必填） |
| `POST /api/v2/channels/{channelId}/ptz/capabilities/refresh` | 刷新视频通道 云台动作 能力。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`devices.control` | channelId（必填） |
| `GET /api/v2/channels/{channelId}/ptz/settings` | 查看设备 云台动作 能力与人工开关。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | channelId（必填） |
| `PUT /api/v2/channels/{channelId}/ptz/settings` | 保存 云台动作 使用开关和 GB28181 未上报能力的管理员确认，不修改设备报告字段。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`channels.manage` | channelId（必填）、SaveChannelPtzSettingsRequest |
| `POST /api/v2/channels/{channelId}/retry` | 清理自动拉流退避状态并立即重试。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`channels.manage` | channelId（必填） |
| `POST /api/v2/channels/{channelId}/return-to-pending` | 将视频通道退回待激活资产池。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | channelId（必填） |
| `GET /api/v2/channels/{channelId}/runtime-logs` | 查询通道运行审计时间线。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | channelId（必填）、Page（必填）、PageSize（必填）、SinceHours（必填）、Level、Category |
| `GET /api/v2/channels/{channelId}/snapshots` | 查询通道周期截图设置、在线状态及带鉴权的图片预览和下载地址。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`streams.play` | channelId（必填） |
| `GET /api/v2/channels/{channelId}/snapshots/{slot}` | 预览或下载指定周期截图JPEG。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`streams.play` | channelId（必填）、slot（必填）、v、download |
| `POST /api/v2/channels/{channelId}/snapshots/access` | 签发绑定当前通道和view/download动作的短时截图票据。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`streams.play` | channelId（必填）、ChannelSnapshotAccessRequest |
| `PUT /api/v2/channels/{channelId}/snapshots/settings` | 05 视频通道与流：PUT /api/v2/channels/{channelId}/snapshots/settings。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | channelId（必填）、ChannelSnapshotSettings |
| `POST /api/v2/channels/{channelId}/start` | 启动视频通道拉流。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`channels.manage` | channelId（必填） |
| `POST /api/v2/channels/{channelId}/stop` | 停流并人工暂停视频通道。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`channels.manage` | channelId（必填） |
| `GET /api/v2/channels/asset-transfer/export` | 导出设备、协议通道、统一通道和分组。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | 无业务参数 |
| `POST /api/v2/channels/asset-transfer/import` | 预览或确认导入接入资产。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | AssetTransferImportRequest |
| `GET /api/v2/channels/groups` | 查询视频设备分组。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | 无业务参数 |
| `POST /api/v2/channels/groups` | 创建视频设备分组。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | SaveChannelGroupRequest |
| `DELETE /api/v2/channels/groups/{groupKey}` | 删除空视频设备分组。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | groupKey（必填） |
| `PUT /api/v2/channels/groups/{groupKey}` | 更新视频设备分组。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`channels.manage` | groupKey（必填）、SaveChannelGroupRequest |
| `GET /api/v2/channels/pending-activation` | 查询待激活视频通道列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | page、pageSize、protocol、deviceId、keyword |
| `GET /api/v2/channels/recording-search/capability` | 查询通道图文检索选项是否可编辑。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`channels.view` | 无业务参数 |
| `GET /api/v2/streams/commands` | 查询流生命周期命令。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`streams.view` | mediaServerId、streamId、state、page、pageSize |
| `GET /api/v2/streams/players` | 查询流媒体服务播放者会话。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`streams.view` | mediaServerId、app、streamId、schema、state、active、page（必填）、pageSize（必填） |
| `GET /api/v2/streams/sessions` | 查询流会话状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`streams.view` | mediaServerId、streamId、state |
| `POST /api/v2/streams/smoke-tests/rtsp` | 执行 RTSP 拉流烟测。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`streams.manage` | RtspSmokeTestRequest |
| `POST /api/v2/streams/smoke-tests/rtsp/batch` | 批量执行 RTSP 拉流烟测。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`streams.manage` | RtspSmokeBatchTestRequest |
| `POST /api/v2/streams/start-proxy` | 创建拉流启动命令。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`streams.manage` | StartStreamCommandRequest |
| `POST /api/v2/streams/stop-proxy` | 创建拉流停止命令。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`streams.manage` | StopStreamCommandRequest |

## 协议统一视图

| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/protocols/{protocol}/devices/{deviceId}` | 查看协议设备。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | protocol（必填）、deviceId（必填） |
| `GET /api/v2/protocols/{protocol}/devices/{deviceId}/channels` | 查询协议设备通道。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | protocol（必填）、deviceId（必填）、page、pageSize、status、channelType、hasAudio、hasPtz、videoChannelId、keyword |
| `POST /api/v2/protocols/{protocol}/devices/{deviceId}/channels` | 保存协议设备通道。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.manage` | protocol（必填）、deviceId（必填）、SaveProtocolChannelRequest |
| `POST /api/v2/protocols/{protocol}/devices/{deviceId}/offline` | 标记协议设备离线。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.manage` | protocol（必填）、deviceId（必填） |
| `POST /api/v2/protocols/{protocol}/devices/{deviceId}/online` | 标记协议设备在线。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.manage` | protocol（必填）、deviceId（必填） |
| `GET /api/v2/protocols/acceptance` | 查看协议验收总览。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | checkDatabase、checkZlm、includeSystemReadiness |
| `GET /api/v2/protocols/alarms/events` | 统一查询 GB28181、ONVIF 等协议告警事件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | page、pageSize、protocol、deviceId、channelId、alarmPriority、alarmMethod、alarmType、ackStatus、begin、end、from、to、sinceHours、keyword |
| `POST /api/v2/protocols/alarms/events/{alarmEventId}/acknowledge` | 确认协议告警事件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.control` | alarmEventId（必填）、ProtocolAlarmDispositionRequest |
| `POST /api/v2/protocols/alarms/events/{alarmEventId}/clear` | 清除协议告警事件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.control` | alarmEventId（必填）、ProtocolAlarmDispositionRequest |
| `POST /api/v2/protocols/alarms/events/{alarmEventId}/ignore` | 忽略协议告警事件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.control` | alarmEventId（必填）、ProtocolAlarmDispositionRequest |
| `POST /api/v2/protocols/alarms/events/{alarmEventId}/status` | 按指定状态更新协议告警事件。 | 做页面概览、运行监控或排障时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.control` | alarmEventId（必填）、ProtocolAlarmStatusUpdateRequest |
| `POST /api/v2/protocols/alarms/events/batch/{action}` | 批量确认、本地清除或忽略协议告警。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.control` | action（必填）、ProtocolAlarmBatchDispositionRequest |
| `GET /api/v2/protocols/alarms/events/stats` | 统计协议告警事件处置状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | protocol、deviceId、channelId、alarmPriority、alarmMethod、alarmType、ackStatus、begin、end、from、to、sinceHours、keyword |
| `GET /api/v2/protocols/channels/orphan-video-bindings` | 查询协议通道孤儿视频绑定。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | page、pageSize、protocol、deviceId、channelId、keyword |
| `POST /api/v2/protocols/channels/orphan-video-bindings/clear` | 清空协议通道孤儿视频绑定。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.control` | ClearProtocolOrphanVideoBindingRequest |
| `GET /api/v2/protocols/commands` | 统一查询 GB28181、ONVIF 等协议命令。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | statusMode、page、pageSize、protocol、status、commandType、deviceId、channelId、nodeId、correlationId、requestedBy、from、to、sinceHours、keyword |
| `GET /api/v2/protocols/commands/{commandId}` | 查看协议命令详情。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | commandId（必填） |
| `GET /api/v2/protocols/commands/{commandId}/detail` | 查看协议命令详情，并联查关联 node 命令。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | commandId（必填） |
| `GET /api/v2/protocols/commands/{commandId}/diagnosis` | 查看单条协议命令的可解释诊断。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | commandId（必填） |
| `GET /api/v2/protocols/commands/diagnostics` | 诊断协议命令失败和超时分布。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | errorOnly、analyzeLimit、bucketLimit、protocol、status、commandType、deviceId、channelId、nodeId、correlationId、requestedBy、from、to、sinceHours、keyword |
| `GET /api/v2/protocols/commands/stats` | 统计协议命令运行状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | protocol、status、commandType、deviceId、channelId、nodeId、correlationId、requestedBy、from、to、sinceHours、keyword |
| `GET /api/v2/protocols/devices` | 查询协议设备列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | page、pageSize、protocol、status、keyword |
| `POST /api/v2/protocols/devices` | 保存协议设备。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.manage` | SaveProtocolDeviceRequest |
| `DELETE /api/v2/protocols/devices/{protocol}/{deviceId}` | 清除待生成通道的协议设备。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.manage` | protocol（必填）、deviceId（必填） |
| `POST /api/v2/protocols/devices/{protocol}/{deviceId}/hard-delete` | 物理删除未激活协议设备的历史残留。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.manage` | protocol（必填）、deviceId（必填）、HardDeletePendingProtocolDeviceRequest |
| `PUT /api/v2/protocols/devices/{protocol}/{deviceId}/name` | 修改协议设备的平台展示名称。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`devices.manage` | protocol（必填）、deviceId（必填）、RenameProtocolDeviceRequest |
| `GET /api/v2/protocols/sessions` | 统一查询 GB28181、ONVIF 等协议流会话。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | page、pageSize、protocol、sessionType、state、deviceId、channelId、mediaServerId、nodeId、app、stream、streamId、ssrc、rtpPort、from、to、sinceHours、keyword |
| `GET /api/v2/protocols/sessions/{sessionId}` | 查看协议流会话详情。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | sessionId（必填） |
| `GET /api/v2/protocols/signals` | 统一查询 GB28181、ONVIF 等协议信令事件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | protocol、eventType、deviceId、channelId、status、keyword、page、pageSize |

## 统一对讲

| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/talk/sessions/{sessionId}` | 查询对讲媒体发送状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`devices.view` | sessionId（必填） |
| `POST /api/v2/talk/sessions/{sessionId}/audio` | 向已建立的 GB28181 或 ONVIF 对讲会话写入 G.711 音频。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`devices.talk` | sessionId（必填）、string |
| `DELETE /api/v2/talk/sessions/{sessionId}/media` | 仅释放对讲媒体发送端。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`devices.talk` | sessionId（必填） |
| `POST /api/v2/talk/sessions/{sessionId}/ptt` | 设置对讲会话 PTT 发送门控。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`devices.talk` | sessionId（必填）、TalkPushToTalkRequest |

## 接口字段与示例

本页故意先讲清业务用途，不把几百个字段塞进说明文字。真正编码时，请使用与部署版本一起提供的 OpenAPI 和 Postman 资产查看请求体、响应体、枚举、文件类型与示例；不要拿网站最新契约调用旧版本服务。