ACS 通話 SDK を使用して、通話間でユーザー間情報 (UUI) のコンテキスト データを渡す
この記事では、Azure Communication Services Calling SDK を使用して通話をルーティングするときに、カスタム コンテキスト情報を渡す方法について説明します。 この機能により、ユーザーは、通話、通話先、またはそれらのアプリケーションやビジネス ロジックに関連するその他の情報に関するメタデータを渡すことができます。
Azure Communication Services (ACS) WebJS SDK を使用すると、開発者は、ユーザー間で通話を転送およびルーティングするときに、カスタムのコンテキスト データを (通話オブジェクトのヘッダーとして) 含めることができます。 この情報 (ユーザー間情報 (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 ヘッダーと 1,000 個のカスタム VOIP ヘッダーがサポートされます。 さらに、開発者は SIP ヘッダー リストの一部として専用のユーザー間ヘッダーを含めることができます。
SIP ヘッダー キーの最大長は、X-MS-Custom プレフィックスを含めて 64 文字です。 SIP ヘッダーが追加されると、通話 SDK によって 'X-MS-Custom-' プレフィックスが自動的に追加されることに注意してください (パケット インスペクターで SIP ヘッダーを検査すると確認できます)。
SIP ヘッダー キーは、英数字といくつかの選択された記号 (.、!、%、*、_、+、~、- など) で構成することができます。 SIP ヘッダー値の最大長は 256 文字です。 SBC で SIP ヘッダーを構成するときも、同じ制限が適用されます。 SIP ヘッダー値は、英数字といくつかの選択された記号 (=、;、.、!、%、*、_、+、~、- など) で構成することができます。
VOIP ヘッダー キーの最大長は 64 文字です。 VOIP ヘッダー値の最大長は 1024 文字です。
開発者としてこれらのカスタム ヘッダーを追加する場合、SIP ヘッダーのみの追加または VoIP ヘッダーのみの追加を選択できます。また、その両方を含めることもできます。
Note
現在、カスタムのユーザー間情報ヘッダーの追加は、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`);
}
}
});