Azure Communication JavaScript 用 Common クライアントライブラリ - バージョン 2.4.0

2025-06-06

このパッケージには、Azure Communication Service ライブラリの共通コードが含まれています。

作業の開始

[前提条件]

Azure サブスクリプション。
既存の Communication Services リソース。リソースを作成する必要がある場合は、Azure Portal、Azure PowerShell、または Azure CLIを使用できます。
@azure/identityパッケージがインストールされていること。

インストール

npm install @azure/communication-common

npm install @azure/identity

ブラウザーサポート

JavaScript バンドル

ブラウザーでこのクライアントライブラリを使用するには、まず、バンドルを使用する必要があります。これを行う方法の詳細については、バンドルドキュメントを参照してください。

重要な概念

CommunicationTokenCredential と AzureCommunicationTokenCredential

CommunicationTokenCredential は、チャットや通話などのコミュニケーションサービスでユーザーを認証するために使用されるインターフェイスです。

この AzureCommunicationTokenCredential は、上記のインターフェイスを実装する資格情報を作成する便利な方法を提供し、組み込みの自動更新ロジックを活用できるようにします。

シナリオによっては、次のように AzureCommunicationTokenCredential を初期化することができます。

静的トークン(1回限りのChatメッセージの送信などに使用される短命のクライアントに適しています)または
通信中に継続的な認証状態を確保するコールバック関数(たとえば、長時間の通話セッションに最適です)。
Entra ユーザートークンを取得できるトークン資格情報。 TokenCredential インターフェイスの任意の実装を提供できます。これは、Communication Services での認証に Entra ユーザーアクセストークンが必要なシナリオに適しています。

コンストラクターまたはトークンリフレッシャーコールバックを介して AzureCommunicationTokenCredential に提供されるトークンは、Azure Communication Identity ライブラリを使用して取得できます。

例示

静的トークンを使用して資格情報を作成する

存続期間の短いクライアントの場合、有効期限が切れたときにトークンを更新する必要はなく、静的トークンを使用して AzureCommunicationTokenCredential をインスタンス化できます。

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

const tokenCredential = new AzureCommunicationTokenCredential(
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
);

コールバックを使用して資格情報を作成する

ここでは、ユーザーの JWT トークン文字列を取得するためのネットワーク要求を行う関数 fetchTokenFromMyServerForUser があると仮定します。それを資格情報に渡して、独自のサーバーからボブのトークンを取得します。私たちのサーバーは、Azure Communication Identity ライブラリを使用してトークンを発行します。 fetchTokenFromMyServerForUser 関数は、常に有効なトークン (有効期限が将来の日付に設定されている) を返す必要があります。

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
});

プロアクティブな更新による資格情報の作成

refreshProactively を true に設定すると、トークンの有効期限が近づいたときに tokenRefresher 関数が呼び出されます。

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
  refreshProactively: true,
});

プロアクティブな更新と初期トークンを使用して資格情報を作成します

initialTokenを渡すことは、tokenRefresherへの最初の呼び出しをスキップするためのオプションの最適化です。これを使用して、アプリケーションからのブートを後続のトークン更新サイクルから分離できます。

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
  refreshProactively: true,
  token:
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
});

Entra ユーザートークンを取得できるトークン資格情報を使用して資格情報を作成します

Entra ユーザーを Communication Services で使用できるシナリオでは、 TokenCredential インターフェイスの実装を初期化し、 EntraCommunicationTokenCredentialOptionsに提供する必要があります。これに加えて、Azure Communication Services リソースの URI と Entra ユーザートークンに必要なスコープを指定する必要があります。これらのスコープは、トークンに付与されるアクセス許可を決定します。

このアプローチは、Teams ライセンスを持つ Entra ユーザーが Azure Communication Services リソースを通じて Teams 電話拡張機能を使用することを承認するために使用する必要があります。これには、 https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls スコープを提供する必要があります。

import { InteractiveBrowserCredential } from "@azure/identity";
import {
  EntraCommunicationTokenCredentialOptions,
  AzureCommunicationTokenCredential,
} from "@azure/communication-common";

const options = {
  tenantId: "<your-tenant-id>",
  clientId: "<your-client-id>",
  redirectUri: "<your-redirect-uri>",
};
const entraTokenCredential = new InteractiveBrowserCredential(options);

const entraTokenCredentialOptions: EntraCommunicationTokenCredentialOptions = {
  resourceEndpoint: "https://<your-resource>.communication.azure.com",
  tokenCredential: entraTokenCredential,
  scopes: ["https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls"],
};

const credential = new AzureCommunicationTokenCredential(entraTokenCredentialOptions);

Entra ユーザーが Azure Communication Services を利用するその他のシナリオは、現在 プレビュー段階のみであり、運用環境では使用しないでください。これらのシナリオのスコープは、 https://communication.azure.com/clients/<ACS Scope> の形式に従います。特定のスコープが指定されていない場合、デフォルトのスコープは https://communication.azure.com/clients/.default に設定されます。

import { InteractiveBrowserCredential } from "@azure/identity";
import {
  EntraCommunicationTokenCredentialOptions,
  AzureCommunicationTokenCredential,
} from "@azure/communication-common";

const options = {
  tenantId: "<your-tenant-id>",
  clientId: "<your-client-id>",
  redirectUri: "<your-redirect-uri>",
};
const entraTokenCredential = new InteractiveBrowserCredential(options);

const entraTokenCredentialOptions: EntraCommunicationTokenCredentialOptions = {
  resourceEndpoint: "https://<your-resource>.communication.azure.com",
  tokenCredential: entraTokenCredential,
  scopes: ["https://communication.azure.com/clients/VoIP"],
};

const credential = new AzureCommunicationTokenCredential(entraTokenCredentialOptions);

トラブルシューティング

無効なトークンが指定されました: AzureCommunicationTokenCredential コンストラクタまたは tokenRefresher コールバックに渡すトークンが、ベアの JWT トークン文字列であることを確認してください。たとえば、 Azure Communication Identity ライブラリまたは REST API を使用してトークンを取得している場合は、応答オブジェクトの token 部分のみを渡していることを確認してください。

ロギング（記録）

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログを有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

次のステップ

コミュニケーションユーザーアクセストークンの詳細を読む

投稿

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

JavaScript 用の Microsoft Azure SDK