この記事では、Azure Communication Services Calling SDK を使用して呼び出しをルーティングするときに、ヘッダーにユーザー間情報 (UUI) を渡す方法について説明します。 この機能により、ユーザーは、呼び出し、呼び出し先、またはアプリケーションまたはビジネス ロジックに関連するその他の情報に関するメタデータを渡すことができます。
Azure Communication Services WebJS SDK を使用すると、開発者は、1 人のユーザーから別のユーザーに呼び出しを転送してルーティングするときに、カスタム コンテキスト データ (呼び出し元オブジェクトのヘッダーとして含まれる) を含めることができます。 この情報は、ユーザー間情報 (UUI) データまたは呼び出し制御 UUI データとも呼ばれ、呼び出しを開始するアプリケーションによって挿入される小さなデータです。 UUI データは、通話を行うエンド ユーザーには不透明です。
サポートされるコンテキスト情報には、フリーフォーム カスタム ヘッダーと標準 UUI SIP ヘッダーの両方が含まれます。 さらに、着信呼び出しを受信すると、カスタム ヘッダーと UUI が incomingCall ペイロードに含まれます。
カスタム コンテキスト データはすべて、Calling SDK または SIP プロトコルに対して不明確なものであり、その内容は基本機能には関連しません。
開発者は、オプションのキーと値のペアで構成されるカスタム ヘッダーを使用して、このコンテキストを渡すことができます。 これらのペアは、呼び出し元 SDK 内の AddParticipant または Transfer アクションに含めることができます。 追加したら、通話がエンドポイント間を移動するときにデータ ペイロードを読み取ることができます。 このメタデータを効率的に検索し、通話に関連付けると、開発者は、外部データベースを検索する必要がなく、通話オブジェクトでコンテンツ情報をすぐに使用できます。
カスタムの通話コンテキストは、SIP プロトコルを使用して SIP エンドポイントに送信できます。 この転送には、カスタム ヘッダーと標準 UUI SIP ヘッダーの両方が含まれます。 着信通話がテレフォニー ネットワークからルーティングされると、カスタム ヘッダーと UUI 内のセッション ボーダー コントローラー (SBC) からのデータも IncomingCall イベント ペイロードに含まれます。
すべてのカスタム コンテキスト データは通話 SDK に対して透過なままであり、SIP プロトコルで使用する場合の SDK の基本機能のいずれにも関連しないことに注意することが重要です。 WebJS SDK を使用する場合にカスタム コンテキスト ヘッダーを追加するのに役立つチュートリアルを次に示します。
重要
呼び出し元の SDK を使用して UUI データを渡すには、呼び出し元の WebJS SDK GA またはパブリック プレビュー バージョン 1.29.1 以降を使用する必要があります。
技術パラメーター
呼び出し元 SDK では、最大 5 つのカスタム SIP ヘッダーと 1000 個のカスタム VOIP ヘッダーの追加がサポートされています。 さらに、開発者は SIP ヘッダー リストの一部として専用のユーザー間ヘッダーを含めることができます。
SIP ヘッダー キーの最大長は、X-MS-Custom プレフィックスを含めて 64 文字です。 呼び出し元の SDK に SIP ヘッダーを追加すると、 X-MS-Custom- プレフィックスが自動的に追加されます。これは、パケット インスペクターを使用して SIP ヘッダーを検査することで確認できます。
SIP ヘッダー キーは、英数字と、 .、 !、 %、 *、 _、 +、 ~、 -など、いくつかの選択されたシンボルで構成される場合があります。 SIP ヘッダー値の最大長は 256 文字です。 セッション ボーダー コントローラー (SBC) で SIP ヘッダーを構成する場合も、同じ制限が適用されます。 SIP ヘッダー値は、英数字と、 =、 ;、 .、 !、 %、 *、 _、 +、 ~、 -など、いくつかの選択されたシンボルで構成される場合があります。
VOIP ヘッダー キーの最大長は 64 文字です。 VOIP ヘッダー値の最大長は 1024 文字です。
開発者としてこれらのカスタム ヘッダーを追加する場合、SIP ヘッダーのみの追加または VoIP ヘッダーのみの追加を選択できます。また、その両方を含めることもできます。
注記
現在、カスタムのユーザー間情報ヘッダーの追加は、1 対 1 の通話を開始する場合にのみサポートされています。 グループ呼び出しでのユーザー間情報ヘッダーの受け渡しは、現在サポートされていません。 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',
},
};
});
通話中にユーザー間情報ヘッダーを読み取り、解析する
ログインしている ID が着信通話を受信すると、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`);
}
}
});