使用 Connection API 管理 Realtime SFU 应用的媒体资源。你的后端发送经过身份验证的 HTTPS 请求,而端点通过 WebRTC 与 SFU 交换媒体和 DataChannels。
基础 URL:
https://rtc.live.cloudflare.com/v1发送 Authorization: Bearer <APP_SECRET> 和 Content-Type: application/json。将 App Secret 保留在受信任的后端基础设施上。端点身份验证和资源授权由你的应用负责。
下载完整 OpenAPI schema 以查看请求和响应字段。
要实现连接,请按照浏览器和后端配方进行发布、接收、消息或带控制的媒体操作。使用本参考查找操作和字段。
在仪表板中或通过 Cloudflare 账户 API 创建 SFU 应用。应用创建使用你的 Cloudflare 账户授权。Connection API 使用生成的 SFU App ID 和 App Secret。
快速入门展示了如何使用 Worker 后端完成此设置。
此表中的路径相对于基础 URL:
| 操作 | 方法和路径 |
|---|---|
| 创建会话 | POST /apps/{appId}/sessions/new |
| 发布或订阅轨道 | POST /apps/{appId}/sessions/{sessionId}/tracks/new |
| 更新轨道 | PUT /apps/{appId}/sessions/{sessionId}/tracks/update |
| 提交重新协商应答 | PUT /apps/{appId}/sessions/{sessionId}/renegotiate |
| 关闭轨道 | PUT /apps/{appId}/sessions/{sessionId}/tracks/close |
| 读取会话信息 | GET /apps/{appId}/sessions/{sessionId} |
有关发布和标识符所有权,请参阅会话和轨道。
sessions/new 上的可选 correlationId 查询参数是诊断标签。重复使用它会创建另一个会话。API 无法按此标签查找会话。请保留返回的 sessionId,如果响应丢失,请遵循恢复指南。
调用 GET /apps/{appId}/sessions/{sessionId} 以检查会话的媒体轨道和 DataChannels。响应通过 mid 标识媒体,通过已分配的 id 标识通道。对于远程资源,sessionId 标识其发布者:
{
"tracks": [
{
"location": "local",
"mid": "0",
"trackName": "camera",
"status": "inactive"
}
],
"dataChannels": [
{
"location": "remote",
"sessionId": "<PUBLISHER_SESSION_ID>",
"dataChannelName": "controls",
"id": 2,
"status": "active"
}
]
}按如下方式解释资源的 status:
| 状态 | 媒体轨道 | DataChannel |
|---|---|---|
active |
尚未关闭或变为不可用。 | 已打开。 |
inactive |
已关闭或不可用。 | 不再连接或打开。 |
initializing |
不适用。 | 仍在连接。 |
标记为 active 的媒体轨道并不证明数据包正在到达或播放。请使用端点统计信息检查交付情况。强制关闭可能使轨道仍列为 inactive。
响应包含资源状态,而不包含 SDP 或请求历史。即使资源列表为空,待处理请求仍可能更改它。在恢复变更操作之前,请遵循重试和重新连接指南。
这些操作作用于与媒体轨道相同的会话和协商状态:
| 操作 | 方法和路径 |
|---|---|
| 建立传输 | POST /apps/{appId}/sessions/{sessionId}/datachannels/establish |
| 发布或订阅通道 | POST /apps/{appId}/sessions/{sessionId}/datachannels/new |
| 更新订阅标志 | PUT /apps/{appId}/sessions/{sessionId}/datachannels/update |
| 关闭通道 | PUT /apps/{appId}/sessions/{sessionId}/datachannels/close |
有关协商 ID、可靠性、就绪状态和回复访问,请参阅 DataChannels。
创建适配器以摄取外部音频,或将现有音频/视频发布流式传输到 WebSocket 端点:
| 操作 | 方法和路径 |
|---|---|
| 创建适配器 | POST /apps/{appId}/adapters/websocket/new |
| 关闭适配器 | POST /apps/{appId}/adapters/websocket/close |
WebSocket 适配器参考涵盖格式、请求限制、部分成功、重新连接和关闭行为。
轨道和 DataChannel 的创建、更新和关闭操作在其 tracks 或 dataChannels 数组中接受多个条目。例如,一起发布摄像头和麦克风轨道,或在一次接收会话调用中请求多个发布。每个批次针对请求 URL 中的会话。
对于 tracks/new 和 datachannels/new,请保持每个条目都为 local 或每个条目都为 remote。远程批次可以引用不同的发布会话。选择批次大小时,请遵循该操作的限制。WebSocket 适配器的创建和关闭每次请求接受 1 到 4 个条目。
检查 HTTP 状态、顶层错误以及每个轨道或通道的结果。公共错误使用 errorCode 和 errorDescription。保留部分成功请求中已成功的分配。在错误代码中查找代码及其后续操作。
在该会话上开始下一次变更之前,完成任何所需的 SDP 交换。其他会话可以独立进行。连接模式给出请求序列,包括如何应答 SFU offer。协商和会话生命周期说明并发处理程序、不确定的请求结果以及重试。
作为连接准备的一部分,配置端点 ICE、STUN 和 TURN。该部分还涵盖连接等待和候选收集。
运行视频房间以跟踪后端会话和轨道操作。DataChannel 示例 ↗在小型本地 Node.js 服务器中展示相同的 API 边界。