你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
使用 ACS 通话 SDK 在通话之间传递上下文用户到用户信息 (UUI) 数据
本文介绍如何在使用 Azure 通信服务通话 SDK 在路由呼叫时传递自定义上下文信息。 此功能让用户可以传递有关呼叫、被叫方或任何其他与应用程序或业务逻辑相关的信息的元数据。
借助 Azure 通信服务 (ACS) WebJS SDK，开发人员可以在将通话从一个人引导并路由到另一个人时包含自定义上下文数据（作为通话对象的标头包含在内）。 此信息也称为用户到用户信息 (UUI) 数据或通话控制 UUI 数据，是由发起通话的应用程序插入的一小部分数据。 UUI 数据对进行通话的最终用户是不可见的。
支持的上下文信息包括自由格式的自定义标头和标准用户到用户信息 (UUI) SIP 标头。 此外，当你收到传入呼叫时，自定义标头和 UUI 会包含在 incomingCall 有效负载中。
所有自定义上下文数据对于通话 SDK 或 SIP 协议都是不透明的，并且其内容与任何基本功能都无关。
开发人员可以使用由可选键值对组成的自定义标头来传递此上下文。 这些对可以包含在通话 SDK 中的“AddParticipant”或“Transfer”操作中。 添加后，可以在通话在终结点之间传递时读取数据有效负载。 通过有效地查找此元数据并将其与通话关联起来，开发人员可以避免外部数据库查找，并可在通话对象中随时获取内容信息。
自定义通话上下文可通过 SIP 协议将传输到 SIP 终结点。 此传输包括自定义标头和标准用户到用户信息 (UUI) SIP 标头。 从电话网络路由入站通话时，来自会话边界控制器 (SBC) 的自定义标头和 UUI 中的数据也包含在 IncomingCall 事件负载中。
请务必注意，所有自定义上下文数据对通话 SDK 都保持透明，并且与 SIP 协议中使用的任何 SDK 基本功能无关。 下面有一个教程，可帮助你在使用 WebJS SDK 时添加自定义上下文标头。
重要
若要使用通话通话 SDK 传递用户到用户信息 (UUI) 数据的功能，必须使用通话 WebJS SDK GA 或公共预览版 1.29.1 或更高版本。
技术参数
通话 SDK 支持添加最多 5 个自定义 SIP 标头和 1000 个自定义 VOIP 标头。 此外，开发人员还可以将专用的用户到用户标头作为 SIP 标头列表的一部分。
SIP 标头键的最大长度为 64 个字符，包括 X-MS-Custom 前缀。 请注意，添加 SIP 标头时，通话 SDK 将自动添加“X-MS-Custom-”前缀（如果通过数据包检查器检查 SIP 标头，可以看到该前缀）。
SIP 标头键可由字母数字字符和一些选定的符号组成，包括 .、!、%、*、_、+、~ 和 -。 SIP 标头值的最大长度为 256 个字符。 在 SBC 上配置 SIP 标头时，同样的限制适用。 SIP 标头值可由字母数字字符和一些选定的符号组成，包括 =、;、.、!、%、*、_、+、~ 和 -。
VOIP 标头键的最大长度为 64 个字符。 VOIP 标头值的最大长度为 1024 个字符。
作为开发人员，在添加这些自定义标头时，可以选择仅添加 SIP 标头、仅添加 VoIP 标头，也可以同时添加这两种标头。
注意
目前，仅当发起一对一通话时，才支持添加自定义用户到用户信息标头。 当前还不支持在群组通话中传递用户到用户信息标头。 为了解决此问题，可以先发起一对一通话，然后在通话中加入其他参与者，同时保留用户到用户信息。
有关自定义上下文接口 API 的详细信息，请参阅自定义上下文 API 资源页。
发起一个包含用户到用户信息 (UUI) 数据的通话
// Setting custom context UUI Headers
const callOptions = {
customContext: {
voipHeaders: [
{key: 'voip-key-1', value: 'voip-value-1'},
{key: 'voip-key-2', value: 'voip-value-2'}
],
sipHeaders: [
{key: 'sip-key-1', value: 'sip-value-1'},
{key: 'sip-key-2', value: 'sip-value-2'}
],
userToUser: 'userToUserHeader',
},
};
});
在通话中读取和分析用户到用户信息标头
当登录的标识收到来电时，callAgent 实例会发出 incomingCall 事件。 若要侦听此事件并提取上下文信息，请使用以下选项之一进行订阅：
let info = '';
callAgent.on("incomingCall", (args) => {
const incomingCall = args.incomingCall;
if (incomingCall.customContext) {
if (incomingCall.customContext.userToUser) {
info += `userToUser: '${incomingCall.customContext.userToUser}'\n`;
}
if (incomingCall.customContext.sipHeaders) {
incomingCall.customContext.sipHeaders.forEach(header => info += `sip: ${header.key}: '${header.value}'\n`);
}
if (incomingCall.customContext.voipHeaders) {
incomingCall.customContext.voipHeaders.forEach(header => info += `voip: ${header.key}: '${header.value}'\n`);
}
}
});