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

DataChannels

最后更新 查看 MarkdownAgent 设置

将 DataChannels 用于聊天、传感器更新和控制事件等应用消息。标准音频和视频传输请使用媒体轨道。

发布端创建一个具名通道。多个订阅者可以接收其消息,并且可以有一名被选中的订阅者在该发布者通道上回复。

发布者
消息
回复
CloudflareRealtime SFU
订阅者
选定的订阅者
发布者消息 →Realtime SFU
Realtime SFU消息 →订阅者
Realtime SFU消息 →选定的订阅者
选定的订阅者已授权的回复 →Realtime SFU
Realtime SFU回复 →发布者

你的后端发起经过认证的 SFU API 调用。浏览器和原生端点拥有对应的 WebRTC 通道。凭据和信令边界见应用架构。

要连接两个端点并发送第一条消息,请遵循完整的消息配方。传输设置把每个端点连接到 SFU。应用通道分配选择要发布或接收的具名消息。

添加应用通道

从 DataChannel 传输已连接的发布端和订阅端开始。各自拥有自己的 SFU 会话和 PeerConnection。这些步骤只添加通道,不重复传输设置。

  1. 在后端调用 POST /apps/{appId}/sessions/{publisherSessionId}/datachannels/new。在请求的 dataChannels 数组中添加一项,设置 location: "local" 和所选的 dataChannelName。检查发布结果,并在订阅前保留成功的分配。
  2. 在订阅者会话上调用 POST /apps/{appId}/sessions/{subscriberSessionId}/datachannels/new。其 dataChannels 项使用 location: "remote"、发布者的 sessionId,以及相同的 dataChannelName。检查订阅结果并保留成功的分配。
  3. 把每个通道的 id 作为 channelId 返回给对应端点。用 pc.createDataChannel(name, { negotiated: true, id: channelId }) 创建浏览器通道。发布者和订阅者 ID 可以不同。此配置默认使用可靠、有序投递。
  4. 安装订阅者的消息处理程序,并等待通道打开。在发布者发送消息前,让订阅者通过你的应用报告就绪。确认订阅者收到该消息。

要在一个会话上分配多个通道,请在一次创建请求中批量放入这些项。该请求应全部是本地发布,或全部是远程订阅。

若需其他投递设置,按下文为每个端点的 API 分配和浏览器通道做配置。整个操作过程中遵循按会话的变更排序。Connection API 提供认证和完整请求 schema。

配置消息投递

发布端为每个具名通道选择一种投递策略:ordered、maxRetransmits 和 maxPacketLifeTime。每个订阅者必须在其 API 请求中镜像该策略,并且每个端点用相同设置配置其浏览器 DataChannel。

同一会话或应用中的通道可以使用不同策略。为不同策略发布独立的具名通道,例如可靠的 commands 和不可靠的 player-state。发布者与其订阅者之间的不对称可靠性不在受支持契约内。

DataChannels 默认使用可靠、有序投递。为每个通道上的消息选择策略:

载荷 示例设置 原因
离散命令或文本 ordered: true,无重传上限 保留消息顺序
彼此独立但都重要的消息 ordered: false,无重传上限 允许乱序,同时保留重传
可替换状态或指针移动 ordered: false,maxRetransmits: 0 允许丢失旧更新

可选投递字段为:

字段 含义
ordered 省略表示 true。设为 false 以允许乱序投递。
maxRetransmits 首次发送后的最大重传次数。设为零表示不重传。
maxPacketLifeTime 尝试发送和重传一条消息的传输时间预算,单位为毫秒。

最多设置 maxRetransmits 和 maxPacketLifeTime 之一。两者都省略表示可靠投递。省略重试上限与设置 maxRetransmits: 0 不同。排序与重试行为相互独立:无序投递仍可以可靠。

maxPacketLifeTime 是传输预算,不是端到端的消息年龄截止时间。使用应用时间戳或序列号丢弃过期更新。可靠投递不提供持久存储,也不确认命令已执行。

你的应用需要把发布者的策略连同发布会话 ID 和通道名称提供给订阅者。用该策略和各自已分配的通道 ID 配置每个浏览器。协商型 DataChannels 不会自动把这些设置传达给浏览器。

waitForAck 和 canReply 按每次订阅单独选择。它们不会改变已发布通道的投递策略。

对于可替换的玩家状态,后端创建发布者分配时使用无序且不重传:

{
	"dataChannels": [
		{
			"location": "local",
			"dataChannelName": "player-state",
			"ordered": false,
			"maxRetransmits": 0
		}
	]
}

检查结果后,将其通道 ID 返回给发布者。在发布者浏览器中,publisherPc 是其 PeerConnection,publisherChannelId 是其已分配 ID:

const publisherChannel = publisherPc.createDataChannel("player-state", {
	negotiated: true,
	id: publisherChannelId,
	ordered: false,
	maxRetransmits: 0,
});

在每个订阅者会话上,后端用相同投递策略请求同一发布:

{
	"dataChannels": [
		{
			"location": "remote",
			"sessionId": "<PUBLISHER_SESSION_ID>",
			"dataChannelName": "player-state",
			"ordered": false,
			"maxRetransmits": 0
		}
	]
}

检查订阅结果后,将其通道 ID 返回给该订阅者。在订阅者浏览器中使用其自己的 subscriberPc 和 subscriberChannelId:

const subscriberChannel = subscriberPc.createDataChannel("player-state", {
	negotiated: true,
	id: subscriberChannelId,
	ordered: false,
	maxRetransmits: 0,
});

云游戏为可靠键盘事件和不可靠指针移动使用独立具名通道。Pocket Radio 把可靠设备消息放在 robot 上,把可替换更新放在 spectrum 上。

等待订阅者就绪(waitForAck)

在远程订阅上设置 waitForAck: true,可在订阅者发出就绪信号前暂停发布者到订阅者的投递。该字段仅适用于 location: "remote",默认值为 false。

本示例订阅一个使用可靠、有序默认值的 device-events 发布。后端在订阅者会话上创建远程订阅:

{
	"dataChannels": [
		{
			"location": "remote",
			"sessionId": "<PUBLISHER_SESSION_ID>",
			"dataChannelName": "device-events",
			"waitForAck": true
		}
	]
}

协商通道打开后,订阅者发送就绪消息:

// channel is the negotiated remote DataChannel for this subscription.
if (channel.readyState === "open") {
	channel.send("ready");
} else {
	channel.addEventListener("open", () => channel.send("ready"), { once: true });
}

SFU 会消费这条第一条消息并打开闸门。它必须在创建远程订阅后 30 秒内到达。否则 SFU 会拆除该闸控通道。重试时请创建新订阅。

此确认建立的是订阅者就绪,不是应用命令确认。在命令之前另发一条就绪消息,并在需要时使用你自己的命令 ID 和确认。

该闸门不是持久重放队列。必须投递的发布者流量应在就绪确认之后再发送。没有 canReply 时,订阅者后续消息不会转发给发布者。

回传给发布者(canReply)

当订阅者需要在同一发布者通道上回复时,设置 canReply: true。该字段仅适用于 location: "remote",默认值为 false。

回复权限具有这些属性:

  • 一个发布者 DataChannel 最多由一名订阅者持有。
  • 授予另一名订阅者会替换先前的选择。
  • 回复只到达发布者,不会转发给其他订阅者。

你的后端必须认证操作者并授权该授予。canReply 控制的是 SFU 回传路径。谁可以获得该权限由应用状态决定。

订阅时允许回复

本示例使用相同的可靠、有序 device-events 策略。后端在接收会话上创建订阅:

{
	"dataChannels": [
		{
			"location": "remote",
			"sessionId": "<PUBLISHER_SESSION_ID>",
			"dataChannelName": "device-events",
			"canReply": true
		}
	]
}

协商通道打开后,该订阅者可以向发布者发送消息。

更改回复权限

要在现有订阅上授予或撤销权限,从后端调用 PUT /apps/{appId}/sessions/{subscriberSessionId}/datachannels/update:

{
	"dataChannels": [
		{
			"location": "remote",
			"sessionId": "<PUBLISHER_SESSION_ID>",
			"dataChannelName": "device-events",
			"canReply": true
		}
	]
}

设置 canReply: false 以撤销权限。用 canReply: true 更新新订阅者以转移权限。在更改应用所显示的控制者状态前,检查每一项结果。

权限授予后,现有协商通道会承载回复。应用示例见 Pocket Radio 的操作者归属 ↗和云游戏控制权归属。

组合确认与回复

一次订阅可以同时设置 waitForAck 和 canReply。其第一条消息打开就绪闸门并被消费。之后的消息在该订阅者持有回复权限期间到达发布者。

关闭通道

在后端发送 PUT /apps/{appId}/sessions/{sessionId}/datachannels/close,并带上该端点会话上已分配的 ID:

{
	"dataChannels": [{ "id": 2 }, { "id": 3 }]
}

按 id 匹配结果。close_track_error 项表示通道不存在或已关闭。保留其他失败或未报告的 ID 以便重试。参见关闭结果处理。

关闭不需要 SDP 交换。先关闭端点的通道对象,不再需要时再关闭其 PeerConnection。若仍有未完成工作,遵循拆除顺序。

自定义媒体载荷

DataChannels 可以把编码媒体作为二进制应用消息承载。SFU 转发这些字节,但不解释其媒体格式。发布和订阅、投递设置、传输拥塞控制以及数据统计仍然适用。

你的应用负责提供媒体分帧、兼容解码器、播放时序、同步,以及从缺失或迟到帧中恢复。控制写入节奏并限制应用缓冲区。SFU 编解码器协商、simulcast 和 WebSocket 媒体适配器作用于媒体轨道。它们不会解释嵌入 DataChannel 消息中的媒体。

通过示例学习

运行 DataChannel 示例 ↗,建立两个端点、打开就绪闸门、发送发布者消息和订阅者回复,并比较无序更新。

该示例把 SFU App Secret 保留在本地 Node.js 服务器上。它是实验性的 localhost 练习,没有公开应用认证或房间成员资格。按其 API 和生命周期指南 ↗查看协商和拆除。

这篇文档对您有帮助吗?