你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
本文介绍如何在使用 Azure 通信服务呼叫 SDK 路由呼叫时，在标头中传递用户到用户信息 (UUI)。 此功能使用户能够传递有关呼叫、被调用方或任何其他与应用程序或业务逻辑相关的信息的元数据。
Azure 通信服务 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 标头，也可以同时添加这两种标头。
注意
发送 SIP 标头时，建议使用 URL 编码标头值。 即使这些值仅包含有效字符，中介运营商也可能无法正确分析它们，除非它们是 URL 编码的。
注意
目前，仅当发起一对一通话时，才支持添加自定义用户到用户信息标头。 目前不支持在群组通话中传递用户至用户信息标头。 若要在开始 1:1 通话后解决此限制，可以在保持通话中的用户间信息的同时添加参与者。
有关自定义上下文接口 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`);
}
}
});