跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Connection API

最后更新 查看 MarkdownAgent 设置

使用 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 或请求历史。即使资源列表为空,待处理请求仍可能更改它。在恢复变更操作之前,请遵循重试和重新连接指南。

DataChannel 操作

这些操作作用于与媒体轨道相同的会话和协商状态:

操作 方法和路径
建立传输 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 适配器操作

创建适配器以摄取外部音频,或将现有音频/视频发布流式传输到 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 边界。

这篇文档对您有帮助吗?