设备P2P对讲播放

设备模块鉴权接口文档 - P2P 接口

概览

• 基础路径: /api
• 文档范围: 设备模块中的 P2P 代理接口
• 鉴权方式: 请求头 X-Token
• Content-Type: application/json

文档拆分

• 本文档仅保留 P2P 代理接口
• 设备基础接口见 device-auth.md
• 直播地址与录像地址接口见 device-auth-address.md

鉴权头

响应说明

• 本文档中的接口由服务端直接代理到设备本地接口。
• 这些接口不走统一 code/msg/data 包装。
• 服务端会直接透传设备原始响应 body 和 HTTP 状态码。
• 若服务端在参数校验阶段失败，则返回统一错误结构。

服务端统一错误格式

{
  "code": 400,
  "msg": "参数错误",
  "data": null
}

1. P2P 建立连接

• 路径: /api/device/p2p/connect
• 方法: POST
• 是否鉴权: 是

Query 参数

Body 参数

当前服务端不校验 body 字段结构，会将原始请求体原样透传给设备。可传空 body 或设备协议要求的 JSON 数据。

请求示例

POST /api/device/p2p/connect?deviceId=dev_001&onlyPlay=0
X-Token: <token>
Content-Type: application/json


{}

返回参数说明

• 服务端直接透传设备端 /xsw/api/p2p/connect 的响应。
• 具体返回字段由设备协议决定，通常会包含会话信息、连接状态等字段。

服务端失败响应示例

{
  "code": 400,
  "msg": "deviceId 不能为空",
  "data": null
}

2. P2P 发送 SDP

• 路径: /api/device/p2p/sdp
• 方法: POST
• 是否鉴权: 是

Query 参数

Body 参数

当前服务端不校验 body 字段结构，会将原始请求体原样透传给设备。通常为设备端要求的 SDP JSON 数据。

请求示例

POST /api/device/p2p/sdp?deviceId=dev_001&sessionId=s123&channelId=1&connectType=1
X-Token: <token>
Content-Type: application/json


{
  "sdp": "offer-sdp-content"
}

返回参数说明

• 服务端直接透传设备端 /xsw/api/p2p/sdp 的响应。
• 具体返回字段由设备协议决定。

服务端失败响应示例

{
  "code": 400,
  "msg": "deviceId 和 sessionId 不能为空",
  "data": null
}

3. P2P 发送 Candidate

• 路径: /api/device/p2p/candidate
• 方法: POST
• 是否鉴权: 是

Query 参数

Body 参数

当前服务端不校验 body 字段结构，会将原始请求体原样透传给设备。通常为 candidate 相关 JSON 数据。

请求示例

POST /api/device/p2p/candidate?deviceId=dev_001&sessionId=s123
X-Token: <token>
Content-Type: application/json


{
  "candidate": "candidate:..."
}

返回参数说明

• 服务端直接透传设备端 /xsw/api/p2p/candidate 的响应。
• 具体返回字段由设备协议决定。

服务端失败响应示例

{
  "code": 400,
  "msg": "deviceId 和 sessionId 不能为空",
  "data": null
}

4. P2P 保活

• 路径: /api/device/p2p/keepalive
• 方法: POST
• 是否鉴权: 是

Query 参数

Body 参数

当前服务端不校验 body 字段结构，会将原始请求体原样透传给设备。可传空 body。

请求示例

POST /api/device/p2p/keepalive?deviceId=dev_001&sessionId=s123
X-Token: <token>
Content-Type: application/json


{}

返回参数说明

• 服务端直接透传设备端 /xsw/api/p2p/keepalive 的响应。
• 具体返回字段由设备协议决定。

服务端失败响应示例

{
  "code": 400,
  "msg": "deviceId 和 sessionId 不能为空",
  "data": null
}

5. P2P 断开连接

• 路径: /api/device/p2p/disconnect
• 方法: POST
• 是否鉴权: 是

Query 参数

Body 参数

当前服务端不校验 body 字段结构，会将原始请求体原样透传给设备。可传空 body。

请求示例

POST /api/device/p2p/disconnect?deviceId=dev_001&sessionId=s123
X-Token: <token>
Content-Type: application/json


{}

返回参数说明

• 服务端直接透传设备端 /xsw/api/p2p/disconnect 的响应。
• 具体返回字段由设备协议决定。

服务端失败响应示例

{
  "code": 400,
  "msg": "deviceId 和 sessionId 不能为空",
  "data": null
}

6. P2P 播放提示音

• 路径: /api/device/p2p/play
• 方法: POST
• 是否鉴权: 是

Query 参数

Body 参数

当前服务端不校验 body 字段结构，会将原始请求体原样透传给设备。可传空 body。

请求示例

POST /api/device/p2p/play?deviceId=dev_001&name=connected.wav&times=1
X-Token: <token>
Content-Type: application/json


{}

返回参数说明

• 服务端直接透传设备端 /xsw/api/p2p/play 的响应。
• 具体返回字段由设备协议决定。

服务端失败响应示例

{
  "code": 400,
  "msg": "deviceId 不能为空",
  "data": null
}

附录

说明

• P2P 相关接口当前仍通过 query 传递 deviceId、sessionId 等参数，并未改为 body 读取。
• 请求 body 由服务端原样透传到设备本地接口。
• 服务端内部转发目标分别为 /xsw/api/p2p/connect、/xsw/api/p2p/sdp、/xsw/api/p2p/candidate、/xsw/api/p2p/keepalive、/xsw/api/p2p/disconnect、/xsw/api/p2p/play。
• 设备返回内容由服务端原样透传，字段结构取决于设备协议。