你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：将数据通道消息传递添加到通话应用

项目
08/06/2024

数据通道功能 API 支持在音频通话和视频通话期间进行实时消息传递。在本快速入门指南中，我们将演示如何集成数据通道功能，以便在群组通话中的参与者之间交换文本消息。请注意，除了“数据通道”功能之外，还有许多不同的消息传递解决方案，应该根据自己具体的使用场景来选择合适的解决方案。

重要

请注意，数据通道功能 API 的当前实现不支持在对等通话场景中的 Web 浏览器与本机应用之间进行直接消息传递。

创建 DataChannelSender 对象

首先，需要创建一个 DataChannelSender 对象来发送消息。在此自定义消息传递应用程序中，建议为 channelId 分配一个数字，用来区分不同的应用程序用例。例如，可以为自定义消息分配 channelId 1000。

const dataChannel = call.feature(Features.DataChannel);
const messageSender = dataChannel.createDataChannelSender({
    channelId: 1000
});

还有其他几个选项，例如可靠性、带宽和优先级。现在可以忽略这些选项，并使用默认值。创建发送方对象时，仍需要接收方对象来接收消息。

注册侦听器以获取 DataChannelReceiver 对象

若要获取接收方对象，需要注册一个侦听器来捕获 dataChannelReceiverCreated 事件。创建接收方对象时，SDK 会连同接收方对象一起发出该事件。

dataChannel.on('dataChannelReceiverCreated', receiver => {
    // receiver.channelId
    // receiver.senderParticipantIdentifier, which shows the sender id
});

在侦听器回调函数中，可以访问接收方对象，并检索 channelId 和发送方参与者 ID senderParticipantIdentifier 之类的信息。由你负责来维护接收方对象引用，因为 SDK 会为所创建的每个接收方对象发出一次事件。

处理 DataChannelReceiver 对象的 messageReady 和 close 事件

当消息到达时，DataChannelReceiver 对象会接收消息，将其存储在内部缓冲区中，并发出 messageReady 事件。无需注册 messageReady 事件侦听器即可接收消息，因为可以随时调用 readMessage API。但是在最佳做法中，我们建议在 messageReady 侦听器回调中读取消息，如果消息处理需要很长时间，可将工作分流给 Web 辅助角色，以使消息接收畅通无阻。

dataChannel.on('dataChannelReceiverCreated', receiver => {
    if (receiver.channelId === 1000) {
        receiver.on('close', () => {
            console.log(`data channel id = ${receiver.channelId} from ${JSON.stringify(receiver.senderParticipantIdentifier)} is closed`);
        });
        receiver.on('messageReady', () => {
            const message = receiver.readMessage();
            // process the message
        });
    }
});

设置参与者

若要指定消息的接收方，可以使用 DataChannelSender.setParticipants API。由发送方对象来维护你提供的最新参与者列表。参与者类型为 CommunicationIdentifier，可从remoteParticipant.identifier 获取。有关详细信息，请参阅访问远程参与者属性。

const user = call.remoteParticipants[0]; // assume the user wants to send a message to the first participant in the remoteParticipants list
messageSender.setParticipants([user.identifier]);

请注意，参与者列表中的参与者人数不得超过 64 人。如果参与者列表为空数组，SDK 会将消息广播给通话中的所有参与者。

发送和接收消息

数据通道功能 API 要求将数据作为 Uint8Array 类型传递。不能使用 sendMessage API 直接发送 JavaScript 字符串。例如，如果要发送字符串 abc，不能使用 sender.sendMessage('abc')。而是需要先将数据序列化到字节缓冲区。

const data = (new TextEncoder()).encode('abc');
sender.sendMessage(data);

下面是发送 JSON 对象的另一个示例。

const obj = {...}; // some object
const data = (new TextEncoder()).encode(JSON.stringify(obj));
sender.sendMessage(data);

接收和解码消息

dataChannel.on('dataChannelReceiverCreated', receiver => {
    if (receiver.channelId === 1000) {
        const textDecoder = new TextDecoder();
        receiver.on('close', () => {
            console.log(`data channel id = ${receiver.channelId} from ${JSON.stringify(receiver.senderParticipantIdentifier)} is closed`);
        });
        receiver.on('messageReady', () => {
            const message = receiver.readMessage();
            const text = textDecoder.decode(message.data);
            console.log(`from ${JSON.stringify(receiver.senderParticipantIdentifier)}:${text}`);
        });
    }
});

可在以下链接中找到完整的示例：https://github.com/Azure-Samples/communication-services-web-calling-tutorial

重要

请注意，当前的数据通道功能 API 不支持在对等通话场景中的 Web 浏览器与本机应用之间进行直接消息传递。

概述

数据通道功能 API 支持在音频通话和视频通话期间进行实时数据消息传递。在本快速入门指南中，我们演示了如何将数据通道功能集成到调用，并使用数据通道 API 通过数据通道发送和接收数据消息。

先决条件

若要使用语音呼叫设置示例应用，请参阅语音呼叫快速入门。

类

“属性”	描述
DataChannelCallFeature	用于启动和管理数据通道功能。
DataChannelSender	用于以发送方身份管理数据通道和发送数据。
DataChannelReceiver	用于以接收方身份管理数据通道和接收数据。
DataChannelSenderOptions	用于表示用于创建数据通道发送方的选项。

枚举

名称	描述
DataChannelPriority	描述数据通道的优先级选项。值：{ `NORMAL`, `HIGH` }。
DataChannelReliability	描述数据通道的可靠性选项。值：{ `LOSSY`, `DURABLE` }。

错误代码

名称	描述
DATA_CHANNEL_FAILED_TO_START	如果出现此错误代码，则 `getDataChannelSender()` 可能失败，指示基础数据通道尚未准备好使用。
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	如果出现此错误代码，则 `getDataChannelSender()` 可能失败，指示已使用所有可用的随机通道 ID。
DATA_CHANNEL_SENDER_CLOSED	如果出现此错误代码，则 `sendMessage()` 可能失败，指示发送方之前已关闭。
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	如果出现此错误代码，则 `sendMessage()` 可能失败，指示消息数据大小超出限制。可以在 `DataChannelSender` 中使用 `getMaxMessageSizeInBytes()` 来获取消息大小限制。
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	如果出现此错误代码，则 `sendMessage()` 可能失败，指示由于带宽不足而发送消息失败。
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	如果出现此错误代码，则 `sendMessage()` 可能失败，指示由于数据通道的总体使用情况不符合流量限制规则，消息发送失败。有关流量限制的详细信息，请参阅数据通道概念文档。

方法

启用数据通道功能

获取在预备步骤中建立的正在进行的呼叫对象。
获取数据通道功能对象。

DataChannelCallFeature dataChannelCallFeature = call.feature(Features.DATA_CHANNEL);

接收数据消息

定义 DataChannelReceiverCreatedListener。

DataChannelReceiverCreatedListener receiverCreatedListener = new DataChannelReceiverCreatedListener() {
    @Override
    public void onReceiverCreated(DataChannelReceiverCreatedEvent e) {
        DataChannelReceiver receiver = e.getReceiver(); // get the new data channel receiver
        int channelId = receiver.getChannelId(); // get the channel id
        CommunicationIdentifier senderId = receiver.getSenderIdentifier(); // get the message sender id
        // listen to the message received event and closed event from this receiver
        // receiver.addOnMessageReceivedListener(messageReceivedlistener);
        // receiver.addOnClosedListener(receiverClosedListener);
    }
};

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

定义 MessageReceivedListener。

MessageReceivedListener messageReceivedListener = new MessageReceivedListener() {
    @Override
    public void onMessageReceived(PropertyChangedEvent e) {
        DataChannelMessage message = e.getReceiver().receiveMessage(); // read the data message from the receiver
        int sequence = message.getSequenceNumber(); // get the message sequence number
        byte[] data = message.getData(); // get the data content
    }
};

定义 ReceiverClosedListener。

ReceiverClosedListener receiverClosedListener = new ReceiverClosedListener() {
    @Override
    public void onReceiverClosed(PropertyChangedEvent e) {
        DataChannelReceiver receiver = e.getReceiver(); // get the data channel receiver to be closed
    }
};

receiver.addOnMessageReceivedListener(messageReceivedlistener);
receiver.addOnClosedListener(receiverClosedListener);

发送数据消息

配置 DataChannelSenderOptions。

DataChannelSenderOptions options = new DataChannelSenderOptions();
options.setChannelId(1000);
options.setBitrateInKbps(32);
options.setPriority(DataChannelPriority.NORMAL);
options.setReliability(DataChannelReliability.LOSSY);

List<CommunicationIdentifier> participants = Arrays.asList( /* identifier1, identifier2, ... */ );
options.setParticipants(participants);

获取 DataChannelSender 并发送数据消息

DataChannelSender dataChannelSender = dataChannelCallFeature.getDataChannelSender(options);

// msgData contains the byte[] data to be sent
dataChannelSender.sendMessage(msgData);

// change participants in the channel if needed
dataChannelSender.setParticipants(new ArrayList<CommunicationIdentifier>());

重要

请注意，当前的数据通道功能 API 不支持在对等通话场景中的 Web 浏览器与本机应用之间进行直接消息传递。

概述

先决条件

若要使用语音呼叫设置示例应用，请参阅语音呼叫快速入门。

类

“属性”	描述
DataChannelCallFeature	用于启动和管理数据通道功能。
DataChannelSender	用于以发送方身份管理数据通道和发送数据。
DataChannelReceiver	用于以接收方身份管理数据通道和接收数据。
DataChannelSenderOptions	用于表示用于创建数据通道发送方的选项。

枚举

名称	描述
DataChannelPriority	描述数据通道的优先级选项。值：{ `normal`, `high` }。
DataChannelReliability	描述数据通道的可靠性选项。值：{ `lossy`, `durable` }。

错误代码

名称	描述
dataChannelFailedToStart	如果出现此错误代码，则 `getDataChannelSender()` 可能失败，指示基础数据通道尚未准备好使用。
dataChannelRandomIdNotAvailable	如果出现此错误代码，则 `getDataChannelSender()` 可能失败，指示已使用所有可用的随机通道 ID。
dataChannelSenderClosed	如果出现此错误代码，则 `sendMessage()` 可能失败，指示发送方之前已关闭。
dataChannelMessageSizeOverLimit	如果出现此错误代码，则 `sendMessage()` 可能失败，指示消息数据大小超出限制。可以在 `DataChannelSender` 中使用 `maxMessageSizeInBytes` 来获取消息大小限制。
dataChannelMessageFailureForBandwidth	如果出现此错误代码，则 `sendMessage()` 可能失败，指示由于带宽不足而发送消息失败。
dataChannelMessageFailureForTrafficLimit	如果出现此错误代码，则 `sendMessage()` 可能失败，指示由于数据通道的总体使用情况不符合流量限制规则，消息发送失败。有关流量限制的详细信息，请参阅数据通道概念文档。

方法

启用数据通道功能

获取在预备步骤中建立的正在进行的呼叫对象。
获取数据通道功能对象。

var dataChannelCallFeature = self.call!.feature(Features.dataChannel)

接收数据消息

let featureDelegate = new FeatureDelegate()
let receiverDelegate = new ReceiverDelegate()
dataChannelCallFeature!.delegate = featureDelegate

class FeatureDelegate: NSObject, DataChannelCallFeatureDelegate {
    public func dataChannelCallFeature(_ dataChannelCallFeature: DataChannelCallFeature, didCreateReceiver args: DataChannelReceiverCreatedEventArgs) {
        let receiver = args.receiver // get the new data channel receiver
        let channelId = receiver.channelId // get the channel id
        let senderId = receiver.senderIdentifier // get the message sender id

        receiver.delegate = receiverDelegate
    }
}

class ReceiverDelegate: NSObject, DataChannelReceiverDelegate {
    public func dataChannelReceiver(_ dataChannelReceiver: DataChannelReceiver, didReceiveMessage args: PropertyChangedEventArgs) {
        let message = dataChannelReceiver.receiveMessage() // read the data message from the receiver
        let sequence = message?.sequenceNumber // get the message sequence number
        let data = message?.data // get the data content
    }
    
    public func dataChannelReceiver(_ dataChannelReceiver: DataChannelReceiver, didClose args: PropertyChangedEventArgs) {
       let channelId = dataChannelReceiver.channelId // get the data channel id to be closed
    }
}

发送数据消息

配置 DataChannelSenderOptions。

let options = new DataChannelSenderOptions()
options.channelId = 1000
options.bitrateInKbps = 32
options.priority = DataChannelPriority.normal
options.reliability = DataChannelReliability.lossy

let communicationIdentifiers: [CommunicationIdentifier] = [ /* identifier1, identifier2, ... */ ]
options.participants = communicationIdentifiers

定义 DataChannelSender 并发送数据消息

DataChannelSender sender = dataChannelCallFeature.getDataChannelSender(options)

// msgData contains the data to be sent
sender.sendMessage(msgData)

// change participants in the channel if needed
let participants: [CommunicationIdentifier] = []
dataChannelSender.setParticipants(participants: participants)

重要

请注意，当前的数据通道功能 API 不支持在对等通话场景中的 Web 浏览器与本机应用之间进行直接消息传递。

概述

先决条件

若要使用语音呼叫设置示例应用，请参阅语音呼叫快速入门。

类

“属性”	描述
DataChannelCallFeature	用于启动和管理数据通道功能。
DataChannelSender	用于以发送方身份管理数据通道和发送数据。
DataChannelReceiver	用于以接收方身份管理数据通道和接收数据。
DataChannelSenderOptions	用于表示用于创建数据通道发送方的选项。

枚举

名称	描述
DataChannelPriority	描述数据通道的优先级选项。值：{ `Normal`, `High` }。
DataChannelReliability	描述数据通道的可靠性选项。值：{ `Lossy`, `Durable` }。

错误代码

名称	描述
DataChannelFailedToStart	如果出现此错误代码，则 `GetDataChannelSender()` 可能失败，指示基础数据通道尚未准备好使用。
DataChannelRandomIdNotAvailable	如果出现此错误代码，则 `GetDataChannelSender()` 可能失败，指示已使用所有可用的随机通道 ID。
DataChannelSenderClosed	如果出现此错误代码，则 `SendMessage()` 可能失败，指示发送方之前已关闭。
DataChannelMessageSizeOverLimit	如果出现此错误代码，则 `SendMessage()` 可能失败，指示消息数据大小超出限制。可以在 `DataChannelSender` 中使用 `MaxMessageSizeInBytes` 来获取消息大小限制。
DataChannelMessageFailureForBandwidth	如果出现此错误代码，则 `SendMessage()` 可能失败，指示由于带宽不足而发送消息失败。
DataChannelMessageFailureForTrafficLimit	如果出现此错误代码，则 `SendMessage()` 可能失败，指示由于数据通道的总体使用情况不符合流量限制规则，消息发送失败。有关流量限制的详细信息，请参阅数据通道概念文档。

方法

启用数据通道功能

获取在预备步骤中建立的正在进行的呼叫对象。
获取数据通道功能对象。

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

接收数据消息

定义 DataChannelReceiverCreated 事件处理程序。

void DataChannelReceiverCreatedHandler(object sender, DataChannelReceiverCreatedEventArgs args) 
{
    DataChannelReceiver receiver = args.Receiver; // get the new data channel receiver
    int channelId = receiver.ChannelId; // get the channel id
    CallIdentifier senderId = receiver.SenderIdentifier; // get the message sender id
    
    // add event handlers for the message received event and closed event from this receiver
    // receiver.MessageReceived += MessageReceivedHandler;
    // receiver.Closed += ReceiverClosedHandler;
}

附加DataChannelReceiverCreatedHandler。

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

定义 MessageReceived 事件处理程序。

void MessageReceivedHandler(object sender, PropertyChangedEventArgs args) 
{
    DataChannelMessage message = (sender as DataChannelReceiver).ReceiveMessage(); // read the data message from the receiver
    long sequence = message.SequenceNumber; // get the message sequence number
    byte[] data = message.Data; // get the data content
}

定义 Closed 事件处理程序。

void ReceiverClosedHandler(object sender, PropertyChangedEventArgs args) 
{
    DataChannelReceiver receiver = sender as DataChannelReceiver; // get the data channel receiver to be closed
};

附加MessageReceivedHandler和ReceiverClosedHandler。

receiver.MessageReceived += MessageReceivedHandler;
receiver.Closed += ReceiverClosedHandler;

发送数据消息

配置 DataChannelSenderOptions。

DataChannelSenderOptions options = new DataChannelSenderOptions();
options.ChannelId = 1000;
options.BitrateInKbps = 32;
options.Priority = DataChannelPriority.Normal;
options.Reliability = DataChannelReliability.Lossy;
var participants = new List<CallIdentifier> { /* identifier1, identifier2, ... */ };
options.Participants = participants.AsReadOnly();

定义 DataChannelSender 并发送数据消息

DataChannelSender sender = dataChannelCallFeature.GetDataChannelSender(options);
// msgData contains the byte[] data to be sent
sender.SendMessage(msgData);
// change participants in the channel if needed
sender.SetParticipants(new List<CallIdentifier>().AsReadOnly());

后续步骤

有关详细信息，请参阅以下文章：

了解数据通道功能概念文档
详细了解通话 SDK 的功能

通过

快速入门：将数据通道消息传递添加到通话应用

创建 DataChannelSender 对象

注册侦听器以获取 DataChannelReceiver 对象

处理 DataChannelReceiver 对象的 messageReady 和 close 事件

设置参与者

发送和接收消息

概述

先决条件

类

枚举

错误代码

方法

启用数据通道功能

接收数据消息

发送数据消息

概述

先决条件

类

枚举

错误代码

方法

启用数据通道功能

接收数据消息

发送数据消息

概述

先决条件

类

枚举

错误代码

方法

启用数据通道功能

接收数据消息

发送数据消息

后续步骤

反馈

其他资源