クイック スタート:アクセス トークンを作成して管理する

アクセス トークンを使用すると、Azure Communication Services SDK は、特定の ID として、Azure Communication Services に対して直接認証を行うことができます。 ユーザーがアプリケーション内の通話またはチャット スレッドに参加できるようにする場合は、アクセス トークンを作成する必要があります。

このクイックスタートでは、Azure Communication Services SDK を使用してアイデンティティを作成し、アクセス トークンを管理する方法を学びます。 運用環境のユースケースでは、サーバーサイドのサービス でアクセス トークンを生成することをお勧めします。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• アクティブな Communication Services リソースと接続文字列。 Communication Services のリソースを作成する。
• Azure CLI をインストールします。

設定

拡張機能の追加

az extension コマンドを使用して、Azure CLI の Azure Communication Services 拡張機能を追加します。

az extension add --name communication

Azure CLI へのサインイン

Azure CLI にサインインする必要があります。 ターミナルから az login コマンドを実行し、資格情報を入力してサインインできます。

(省略可能) 接続文字列を渡さずに Azure CLI の ID 操作を使用する

--connection_string を使用して接続文字列を渡すことなく Azure CLI の ID 操作を使用するために、AZURE_COMMUNICATION_CONNECTION_STRING 環境変数を構成できます。 環境変数を構成するには、コンソール ウィンドウを開き、以下のタブからお使いのオペレーティン グシステムを選択します。 <yourConnectionString> は、実際の接続文字列に置き換えてください。

Windows

コンソール ウィンドウを開き、次のコマンドを入力します。

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

実行中のプログラムのうち、環境変数の読み取りを必要とするプログラム (コンソール ウィンドウを含む) については、環境変数を追加した後で再起動が必要となる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

macOS

次のように .zshrc を編集し、環境変数を追加します。

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.zshrc を実行します。 IDE が開いている状態で環境変数を作成した場合、その変数にアクセスするには、エディター、IDE、またはシェルを閉じて、再度開くことが必要な場合があります。

Linux

次のように .bash_profile を編集し、環境変数を追加します。

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.bash_profile を実行します。 IDE が開いている状態で環境変数を作成した場合、その変数にアクセスするには、エディター、IDE、またはシェルを閉じて、再度開くことが必要な場合があります。

環境変数にアクセス トークンを格納する

環境変数を構成するには、コンソール ウィンドウを開き、以下のタブからお使いのオペレーティン グシステムを選択します。 <yourAccessToken> は、実際のアクセス トークンに置き換えてください。

Windows

コンソール ウィンドウを開き、次のコマンドを入力します。

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

実行中のプログラムのうち、環境変数の読み取りを必要とするプログラム (コンソール ウィンドウを含む) については、環境変数を追加した後で再起動が必要となる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

macOS

次のように .zshrc を編集し、環境変数を追加します。

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.zshrc を実行します。 IDE が開いている状態で環境変数を作成した場合、その変数にアクセスするには、エディター、IDE、またはシェルを閉じて、再度開くことが必要な場合があります。

Linux

次のように .bash_profile を編集し、環境変数を追加します。

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.bash_profile を実行します。 IDE が開いている状態で環境変数を作成した場合、その変数にアクセスするには、エディター、IDE、またはシェルを閉じて、再度開くことが必要な場合があります。

操作

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 user create コマンドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。 ID は、後でアクセス トークンを発行するのに必要になります。

az communication identity user create --connection-string "<yourConnectionString>"

• <yourConnectionString> を対象の接続文字列に置き換えてください。

ID を作成し、同じ要求内でアクセス トークンを発行する

次のコマンドを実行して、Communication Services ID を作成し、同時にそのアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細は、「Azure Communication Services への認証」でサポートされているアクションの一覧を参照してください。

az communication identity token issue --scope chat --connection-string "<yourConnectionString>"

コードで次の置き換えを行います。

• <yourConnectionString> を対象の接続文字列に置き換えてください。

アクセス トークンの発行

次のコマンドを実行して、Communication Services ID のアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細は、「Azure Communication Services への認証」でサポートされているアクションの一覧を参照してください。

az communication identity token issue --scope chat --user "<userId>" --connection-string "<yourConnectionString>"

コードで次の置き換えを行います。

• <yourConnectionString> を対象の接続文字列に置き換えてください。
• <userId> を対象のユーザー ID に置き換えてください。

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expires_on 応答プロパティは、アクセス トークンの有効期間を示します。

複数のスコープを持つアクセス トークンを発行する

次のコマンドを実行して、Communication Services ID の複数のスコープを持つアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。

az communication identity token issue --scope chat voip --user "<userId>" --connection-string "<yourConnectionString>"

コードで次の置き換えを行います。

• <yourConnectionString> を対象の接続文字列に置き換えてください。
• <userId> を対象のユーザー ID に置き換えてください。

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expires_on 応答プロパティは、アクセス トークンの有効期間を示します。

Teams ユーザーの Microsoft Entra アクセス トークンを通信 ID アクセス トークンに置き換える

token get-for-teams-user コマンドを使用して、Azure Communication Services SDK で使用できる Teams ユーザーのアクセス トークンを発行します。

az communication identity token get-for-teams-user --aad-token "<yourAadToken>" --client "<yourAadApplication>" --aad-user "<yourAadUser>" --connection-string "<yourConnectionString>"

コードで次の置き換えを行います。

• <yourConnectionString> を対象の接続文字列に置き換えてください。
• <yourAadUser> をお使いの Microsoft Entra userId に置き換えます。
• <yourAadApplication> をお使いの Microsoft Entra アプリケーション ID に置き換えます。
• <yourAadToken> をお使いの Microsoft Entra アクセス トークンに置き換えます。

アクセス トークンの取り消し

場合によっては、アクセス トークンを明示的に失効させる必要があるかもしれません。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 token revoke コマンドを使用すると、ID に対して発行されたすべてのアクティブなアクセス トークンを無効にできます。

az communication identity token revoke --user "<userId>" --connection-string "<yourConnectionString>"

コードで次の置き換えを行います。

• <yourConnectionString> を対象の接続文字列に置き換えてください。
• <userId> を対象のユーザー ID に置き換えてください。

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

az communication identity user delete --user "<userId>" --connection-string "<yourConnectionString>"

コードで次の置き換えを行います。

• <yourConnectionString> を対象の接続文字列に置き換えてください。
• <userId> を対象のユーザー ID に置き換えてください。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• お使いのオペレーティング システムに対応した最新の .NET Core SDK バージョン。
• アクティブな Communication Services リソースと接続文字列。 Communication Services リソースを作成します。

最終的なコード

このクイックスタートの最終的なコードは GitHub にあります。

環境を設定する

新しい C# アプリケーションを作成する

コマンド プロンプト ウィンドウで、cmd、PowerShell、Bash などのコンソール ウィンドウで dotnet new コマンドを実行して、新しいコンソール アプリを AccessTokensQuickstart という名前で作成します。 このコマンドにより、1 つのソース ファイル (Program.cs) を含む単純な "Hello World" C# プロジェクトが作成されます。

dotnet new console -o AccessTokensQuickstart

ディレクトリを、新しく作成したアプリ フォルダーに変更し、dotnet build コマンドを使用して自分のアプリケーションをコンパイルします。

cd AccessTokensQuickstart
dotnet build

簡単な "Hello World" 出力が表示されます。 そうであれば、セットアップは正しく機能しているので、Azure Communication Services 固有のコードを書き始めることができます。

パッケージをインストールする

まだアプリケーション ディレクトリにいる間に、dotnet add package コマンドを使用して、.NET 用の Azure Communication Services ID ライブラリ パッケージをインストールします。

dotnet add package Azure.Communication.Identity

アプリのフレームワークを設定する

プロジェクト ディレクトリから、次の操作を行います。

1. テキスト エディターで Program.cs ファイルを開きます。
2. using ディレクティブを追加して、Azure.Communication.Identity 名前空間を含めます。
3. 非同期コードをサポートするように Main メソッドの宣言を更新します。

開始するには、次のコードを実行します。

using System;
using Azure;
using Azure.Core;
using Azure.Communication.Identity;

namespace AccessTokensQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Access Tokens Quickstart");

            // Quickstart code goes here
        }
    }
}

クライアントを認証する

接続文字列を使用して CommunicationIdentityClient を初期化します。 Main メソッドに追加した次のコードは、COMMUNICATION_SERVICES_CONNECTION_STRING という名前の環境変数からリソースの接続文字列を取得します。

詳細については、「Communication Services リソースの作成と管理」の「接続文字列を保存する」セクションを参照してください。

// This code demonstrates how to retrieve your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
var client = new CommunicationIdentityClient(connectionString);

また、以下のコードを実行することで、エンドポイントとアクセスキーを分離することができます。

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
string endpoint = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ENDPOINT");
string accessKey = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ACCESSKEY");
var client = new CommunicationIdentityClient(new Uri(endpoint), new AzureKeyCredential(accessKey));

Microsoft Entra アプリケーションを既に設定している場合は、Microsoft Entra ID を使って認証できます。

TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 createUser メソッドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。 ID は、後でアクセス トークンを発行するのに必要になります。

var identityResponse = await client.CreateUserAsync();
var identity = identityResponse.Value;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");

受信した ID をアプリケーションのユーザーにマッピングして保存します (例えば、アプリケーション サーバーのデータベースに保存します)。

アクセス トークンを発行する

Communication Services の ID を取得したら、GetToken メソッドを使用してその ID 用のアクセストークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。 また、Azure Communication Service の ID の文字列表現に基づいて、communicationUser の新しいインスタンスを構築することもできます。

// Issue an access token with a validity of 24 hours and the "voip" scope for an identity
var tokenResponse = await client.GetTokenAsync(identity, scopes: new [] { CommunicationTokenScope.VoIP });

// Get the token from the response
var token =  tokenResponse.Value.Token;
var expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expiresOn プロパティは、アクセス トークンの有効期間を示します。

カスタム トークンの有効期限を設定する

既定のトークンの有効期限は 24 時間ですが、省略可能なパラメーター tokenExpiresIn に 1 時間から 24 時間の値を指定することで有効期限を構成できます。 新しいトークンを要求するときは、トークンの有効期限に対して通信セッションの予想される一般的な長さを指定することをお勧めします。

// Issue an access token with a validity of an hour and the "voip" scope for an identity 
TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
CommunicationTokenScope[] scopes = new[] { CommunicationTokenScope.VoIP };
var tokenResponse = await client.GetTokenAsync(identity, scopes, tokenExpiresIn);

同じ要求で id を作成し、トークンを発行する

CreateUserAndTokenAsync メソッドを使用して、Communication Services ID を作成し、同時にそのアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細は、「Azure Communication Services への認証」でサポートされているアクションの一覧を参照してください。

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
var identityAndTokenResponse = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.VoIP });

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.Value.User;
var token = identityAndTokenResponse.Value.AccessToken.Token;
var expiresOn = identityAndTokenResponse.Value.AccessToken.ExpiresOn;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

アクセス トークンを更新する

アクセス トークンを更新するには、CommunicationUserIdentifier オブジェクトのインスタンスを GetTokenAsync に渡します。 この Id を保存済みであり、新しい CommunicationUserIdentifier を作成する必要がある場合、これを行うには、次のように保存済みの Id を CommunicationUserIdentifier コンストラクターに渡します。

var identityToRefresh = new CommunicationUserIdentifier(identity.Id);
var tokenResponse = await client.GetTokenAsync(identityToRefresh, scopes: new [] { CommunicationTokenScope.VoIP });

アクセス トークンの取り消し

場合によっては、アクセス トークンを明示的に失効させる必要があるかもしれません。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 RevokeTokensAsync メソッドを使用すると、ID に対して発行されたすべてのアクティブなアクセス トークンを無効にできます。

await client.RevokeTokensAsync(identity);
Console.WriteLine($"\nSuccessfully revoked all access tokens for identity with ID: {identity.Id}");

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

await client.DeleteUserAsync(identity);
Console.WriteLine($"\nDeleted the identity with ID: {identity.Id}");

コードの実行

アクセス トークンの作成が完了したら、アプリケーション ディレクトリから dotnet run コマンドを使ってアプリケーションを実行します。

dotnet run

アプリの出力には、完了した各アクションが表示されます。

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 10/11/2022 7:34:29 AM +00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 10/11/2022 7:34:29 AM +00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• Node.js アクティブ LTS およびメンテナンス LTS バージョン (8.11.1 および 10.14.1 を推奨)。
• アクティブな Communication Services リソースと接続文字列。 Communication Services リソースを作成します。

最終的なコード

このクイックスタートの最終的なコードは GitHub にあります。

環境を設定する

新しい Node.js アプリケーションを作成する

ターミナルまたはコマンドプロンプトウィンドウで、アプリ用の新しいディレクトリを作成し、それを開きます。

mkdir access-tokens-quickstart && cd access-tokens-quickstart

既定の設定で npm init -y を実行して、package.json ファイルを作成します。

npm init -y

パッケージをインストールする

npm install コマンドを使用して、JavaScript 用の Azure Communication Services Identity SDK をインストールします。

npm install @azure/communication-identity@latest --save

--save オプションを使用すると、package.json ファイル内の依存関係としてライブラリが表示されます。

アプリのフレームワークを設定する

1. プロジェクト ディレクトリに issue-access-token.js という名前のファイルを作成し、次のコードを追加します。

   const { CommunicationIdentityClient } = require('@azure/communication-identity');
   
   const main = async () => {
     console.log("Azure Communication Services - Access Tokens Quickstart")
   
     // Quickstart code goes here
   };
   
   main().catch((error) => {
     console.log("Encountered an error");
     console.log(error);
   })
   

クライアントを認証する

接続文字列を使用して CommunicationIdentityClient をインスタンス化します。 Main メソッドに追加した次のコードは、COMMUNICATION_SERVICES_CONNECTION_STRING という名前の環境変数からリソースの接続文字列を取得します。

詳細については、「Communication Services リソースの作成と管理」の「接続文字列を保存する」セクションを参照してください。

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(connectionString);

また、以下のコードを実行することで、エンドポイントとアクセスキーを分離することができます。

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const accessKey = process.env["COMMUNICATION_SERVICES_ACCESSKEY"];

// Create the credential
const tokenCredential = new AzureKeyCredential(accessKey);

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential)

Microsoft Entra アプリケーションを既に設定している場合は、Microsoft Entra ID を使って認証できます。

const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const tokenCredential = new DefaultAzureCredential();
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential);

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 createUser メソッドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。 ID は、後でアクセス トークンを発行するのに必要になります。

let identityResponse = await identityClient.createUser();
console.log(`\nCreated an identity with ID: ${identityResponse.communicationUserId}`);

受信した ID をアプリケーションのユーザーにマッピングして保存します (例えば、アプリケーション サーバーのデータベースに保存します)。

アクセス トークンを発行する

getToken メソッドを使用して、Communication Services の ID のアクセストークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。 また、Azure Communication Service の ID の文字列表現に基づいて、communicationUser の新しいインスタンスを構築することもできます。

// Issue an access token with a validity of 24 hours and the "voip" scope for an identity
let tokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

// Get the token and its expiration date from the response
const { token, expiresOn } = tokenResponse;
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expiresOn プロパティは、アクセス トークンの有効期間を示します。

カスタム トークンの有効期限を設定する

既定のトークンの有効期限は 24 時間 (1440 分) ですが、省略可能なパラメーター tokenExpiresInMinutes に 60 分から 1440 分の値を指定することで有効期限を構成できます。 新しいトークンを要求するときは、トークンの有効期限に対して通信セッションの予想される一般的な長さを指定することをお勧めします。

// Issue an access token with a validity of an hour and the "voip" scope for an identity
const tokenOptions: GetTokenOptions = { tokenExpiresInMinutes: 60 };
let tokenResponse = await identityClient.getToken
(identityResponse, ["voip"], tokenOptions);

ID を作成し、1 つのメソッド呼び出しでトークンを発行する

createUserAndToken メソッドを使用して、Communication Services ID を作成し、同時にそのアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 ここでも、voip スコープで作成します。

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
let identityTokenResponse = await identityClient.createUserAndToken(["voip"]);

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

アクセス トークンを更新する

トークンは有効期限が切れるので、定期的に更新する必要があります。 更新は、トークンの発行に使用したものと同じ ID を使用して getToken を再度呼び出すだけで簡単に行うことができます。 更新されるトークンの scopes を指定する必要があります。

// Value of identityResponse represents the Azure Communication Services identity stored during identity creation and then used to issue the tokens being refreshed
let refreshedTokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

アクセス トークンの取り消し

アクセス トークンを失効させる必要がある場合もあります。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 revokeTokens メソッドを使用すると、ID に対して発行されたすべてのアクティブなアクセス トークンを無効にできます。

await identityClient.revokeTokens(identityResponse);

console.log(`\nSuccessfully revoked all access tokens for identity with ID: ${identityResponse.communicationUserId}`);

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

await identityClient.deleteUser(identityResponse);

console.log(`\nDeleted the identity with ID: ${identityResponse.communicationUserId}`);

コードの実行

コンソール プロンプトから、issue-access-token.js ファイルのあるディレクトリに移動し、以下の node コマンドを実行してアプリを実行します。

node ./issue-access-token.js

アプリの出力には、完了した各アクションが表示されます。

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• Python 3.8 以降。
• アクティブな Communication Services リソースと接続文字列。 Communication Services リソースを作成します。

最終的なコード

このクイックスタートの最終的なコードは GitHub にあります。

環境を設定する

新しい Python アプリケーションを作成する

1. ターミナルまたはコマンド プロンプト ウィンドウで、アプリ用の新しいディレクトリを作成し、それを開きます。

   mkdir access-tokens-quickstart && cd access-tokens-quickstart
   

2. テキスト エディターを使用して、issue-access-tokens.py という名前のファイルをプロジェクトのルート ディレクトリに作成し、基本的な例外処理を含むプログラムの構造を追加します。 このクイックスタートのすべてのソースコードを、この後のセクションでこのファイルに追加します。

   import os
   from datetime import timedelta
   from azure.communication.identity import CommunicationIdentityClient, CommunicationUserIdentifier
   
   try:
      print("Azure Communication Services - Access Tokens Quickstart")
      # Quickstart code goes here
   except Exception as ex:
      print("Exception:")
      print(ex)
   

パッケージをインストールする

引き続きアプリケーション ディレクトリで、pip install コマンドを使用して、Python 用の Azure Communication Services ID SDK パッケージをインストールします。

pip install azure-communication-identity

クライアントを認証する

接続文字列を使用して CommunicationIdentityClient をインスタンス化します。 try ブロックに追加した次のコードは、COMMUNICATION_SERVICES_CONNECTION_STRING という名前の環境変数からリソースの接続文字列を取得します。

詳細については、「Communication Services リソースの作成と管理」の「接続文字列を保存する」セクションを参照してください。

# This code demonstrates how to retrieve your connection string
# from an environment variable.
connection_string = os.environ["COMMUNICATION_SERVICES_CONNECTION_STRING"]

# Instantiate the identity client
client = CommunicationIdentityClient.from_connection_string(connection_string)

または、Microsoft Entra アプリケーションを既に設定している場合は、Microsoft Entra ID を使って認証できます。

endpoint = os.environ["COMMUNICATION_SERVICES_ENDPOINT"]
client = CommunicationIdentityClient(endpoint, DefaultAzureCredential())

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 create_user メソッドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。 ID は、後でアクセス トークンを発行するのに必要になります。

identity = client.create_user()
print("\nCreated an identity with ID: " + identity.properties['id'])

受信した ID をアプリケーションのユーザーにマッピングして保存します (例えば、アプリケーション サーバーのデータベースに保存します)。

アクセス トークンを発行する

get_token メソッドを使用して、Communication Services の ID のアクセストークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。 また、Azure Communication Service のアイデンティティの文字列表現に基づいて、パラメーター CommunicationUserIdentifier の新しいインスタンスを構築することもできます。

# Issue an access token with a validity of 24 hours and the "voip" scope for an identity
token_result = client.get_token(identity, ["voip"])
print("\nIssued an access token with 'voip' scope that expires at " + token_result.expires_on + ":")
print(token_result.token)

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expires_on 応答プロパティは、アクセス トークンの有効期間を示します。

カスタム トークンの有効期限を設定する

既定のトークンの有効期限は 24 時間ですが、省略可能なパラメーター token_expires_in に 1 時間から 24 時間の値を指定することで有効期限を構成できます。 新しいトークンを要求するときは、トークンの有効期限に対して通信セッションの予想される一般的な長さを指定することをお勧めします。

# Issue an access token with a validity of an hour and the "voip" scope for an identity
token_expires_in = timedelta(hours=1)
token_result = client.get_token(identity, ["voip"], token_expires_in=token_expires_in)

ID を作成し、同じ要求内でアクセス トークンを発行する

create_user_and_token メソッドを使用して、Communication Services ID を作成し、同時にそのアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細は、「Azure Communication Services への認証」でサポートされているアクションの一覧を参照してください。

# Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
identity_token_result = client.create_user_and_token(["voip"])

# Get the token details from the response
identity = identity_token_result[0]
token = identity_token_result[1].token
expires_on = identity_token_result[1].expires_on
print("\nCreated an identity with ID: " + identity.properties['id'])
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token)

アクセス トークンを更新する

アクセス トークンを更新するには、CommunicationUserIdentifier オブジェクトを使用し、既存の ID を渡してトークンを再発行します。

# The existingIdentity value represents the Communication Services identity that's stored during identity creation
identity = CommunicationUserIdentifier(existingIdentity)
token_result = client.get_token(identity, ["voip"])

アクセス トークンの取り消し

場合によっては、アクセス トークンを明示的に失効させる必要があるかもしれません。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 revoke_tokens メソッドを使用すると、ID に対して発行されたすべてのアクティブなアクセス トークンを無効にできます。

client.revoke_tokens(identity)
print("\nSuccessfully revoked all access tokens for identity with ID: " + identity.properties['id'])

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

client.delete_user(identity)
print("\nDeleted the identity with ID: " + identity.properties['id'])

コードの実行

コンソール プロンプトから、issue-access-tokens.py ファイルのあるディレクトリに移動し、以下の python コマンドを実行してアプリを実行します。

python ./issue-access-tokens.py

アプリの出力には、完了した各アクションが表示されます。

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• Java Development Kit (JDK) バージョン 8 以降。
• Apache Maven。
• アクティブな Communication Services リソースと接続文字列。 Communication Services リソースを作成します。

最終的なコード

このクイックスタートの最終的なコードは GitHub にあります。

環境を設定する

新しい Java アプリケーションを作成する

ターミナルまたはコマンド プロンプト ウィンドウで、Java アプリケーションを作成するディレクトリに移動します。 maven-archetype-quickstart テンプレートから Java プロジェクトを生成するには、以下のコードを実行します。

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

generate タスクが artifactId と同じ名前のディレクトリを作成していることがわかります。 このディレクトリの下の src/main/java ディレクトリにはプロジェクトのソース コードが、src/test/java ディレクトリにはテスト ソースがそれぞれ含まれており、pom.xml ファイルはプロジェクトのプロジェクト オブジェクト モデル (POM) です。 このファイルは、プロジェクトの構成パラメーターに使用されます。

Communication Services パッケージをインストールする

テキスト エディターで pom.xml ファイルを開きます。 依存関係のグループに、次の dependency 要素を追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
    <version>[1.4.0,)</version>
</dependency>

このコードは、後に使用する Communication Services Identity SDK をインストールするように Maven に指示しています。

アプリのフレームワークを設定する

プロジェクト ディレクトリから、次の操作を行います。

1. /src/main/java/com/communication/quickstart ディレクトリに移動します
2. 使用しているエディターで App.java ファイルを開きます
3. System.out.println("Hello world!"); ステートメントを置き換えます
4. import ディレクティブを追加します。

次のコードを使用して開始します。

package com.communication.quickstart;

import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.core.credential.*;

import java.io.IOException;
import java.time.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Access Tokens Quickstart");
        // Quickstart code goes here
    }
}

クライアントを認証する

リソースのアクセス キーとエンドポイントを使用して、CommunicationIdentityClient をインスタンス化します。 詳細については、「Communication Services リソースの作成と管理」の「接続文字列を保存する」セクションを参照してください。

さらに、クライアントは、com.azure.core.http.HttpClient インターフェイスを実装する任意のカスタム HTTP クライアントを使用して初期化できます。

App.java ファイルで、main メソッドに以下のコードを追加します。

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
String accessKey = "SECRET";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(new AzureKeyCredential(accessKey))
        .buildClient();

エンドポイントとアクセス キーを指定する代わりに、connectionString() メソッドを使って接続文字列全体を指定することができます。

// You can find your connection string from your Communication Services resource in the Azure portal
String connectionString = "<connection_string>";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Microsoft Entra アプリケーションを既に設定している場合は、Microsoft Entra ID を使って認証できます。

String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(credential)
        .buildClient();

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 createUser メソッドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("\nCreated an identity with ID: " + user.getId());

作成した ID は、後でアクセス トークンを発行するのに必要になります。 受信した ID をアプリケーションのユーザーにマッピングして保存します (例えば、アプリケーション サーバーのデータベースに保存します)。

アクセス トークンを発行する

getToken メソッドを使用して、Communication Services の ID のアクセストークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。

次のコードでは、前のステップで作成したユーザー変数を使って、トークンを取得します。

// Issue an access token with a validity of 24 hours and the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes);
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'voip' scope that expires at: " + expiresAt + ": " + token);

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expiresAt プロパティは、アクセス トークンの有効期間を示します。

カスタム トークンの有効期限を設定する

既定のトークンの有効期限は 24 時間ですが、省略可能なパラメーター tokenExpiresIn に 1 時間から 24 時間の値を指定することで有効期限を構成できます。 新しいトークンを要求するときは、トークンの有効期限に対して通信セッションの予想される一般的な長さを指定することをお勧めします。

// Issue an access token with a validity of an hour and the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
Duration tokenExpiresIn = Duration.ofHours(1);
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes, tokenExpiresIn);

1 つの要求で ID を作成し、トークンを発行する

また、'createUserAndToken' メソッドを使って、ディレクトリに一意の Id で新しいエントリを作成し、同時にアクセストークンを発行することもできます。

//Create an identity and issue token with a validity of 24 hours in one call
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
CommunicationUserIdentifier user = result.getUser();
System.out.println("\nCreated a user identity with ID: " + user.getId());
AccessToken accessToken = result.getUserToken();
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'chat' scope that expires at: " + expiresAt + ": " + token);

アクセス トークンを更新する

アクセス トークンを更新するには、CommunicationUserIdentifier オブジェクトを使用して再発行します。

// existingIdentity represents the Communication Services identity that's stored during identity creation
CommunicationUserIdentifier identity = new CommunicationUserIdentifier(existingIdentity.getId());
AccessToken response = communicationIdentityClient.getToken(identity, scopes);

アクセス トークンを取り消す

場合によっては、アクセス トークンを明示的に失効させる必要があるかもしれません。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 revokeTokens メソッドを使用すると、特定のユーザーのすべてのアクティブなアクセス トークンを無効にできます。 以下のコードでは、以前に作成したユーザーを使用しています。

communicationIdentityClient.revokeTokens(user);
System.out.println("\nSuccessfully revoked all access tokens for user identity with ID: " + user.getId());

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

communicationIdentityClient.deleteUser(user);
System.out.println("\nDeleted the user identity with ID: " + user.getId());

コードの実行

pom.xml ファイルのあるディレクトリに移動し、以下の mvn コマンドでプロジェクトをコンパイルします。

mvn compile

次に、パッケージをビルドします

mvn package

次の mvn コマンドを実行して、アプリを実行します。

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

アプリの出力には、完了した各アクションが表示されます。

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.902864800Z:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'chat' scope that expires at 2022-10-11T07:34:29.902864800Z:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

前提条件

• Azure Communication Services のリソース。

アクセス トークンの作成

Azure portal で、Communication Services リソース内で ID とユーザーアクセス トークンのブレードまで移動します。

アクセス トークンのスコープを選択します。 なし、1 つ、または複数を選択できます。 [生成] をクリックします。

ID と、対応するユーザー アクセス トークンが生成されます。 これらの文字列をコピーし、サンプル アプリやそのほかのテスト シナリオで使用できます。

前提条件

• アクティブなサブスクリプションを含む Azure アカウント。または、アカウントを無料で作成してください。

• アクティブな Azure Communication Services リソース。または、Communication Services リソースを作成してください。

• アクティブな Azure Logic Apps リソース (ロジック アプリ)。または、使用するトリガーを追加した従量課金プラン ロジック アプリ ワークフローを作成します。 現在、Azure Communication Services Identity コネクタではアクションのみが提供されているため、ロジック アプリには最低でもトリガーが必要となります。

ユーザーの作成

Azure Communication Services Identity コネクタを使用してワークフローに新しいステップを追加します。Power Automate フローを編集モードで開いた状態で Power Automate の次の手順に従います。

1. デザイナーで、新しいアクションの追加先となるステップで [新しいステップ] を選択します。 ステップとステップの間に新しいアクションを追加するには、それらのステップ間の矢印にポインターを合わせて、正符号 (+) を選択し、[アクションの追加] を選択します。

2. [操作を選択してください] 検索ボックスに、「Communication Services Identity」と入力します。 アクションの一覧から [ユーザーの作成] を選択します。

   

3. 接続文字列を指定します。 これは Microsoft Azure の Azure Communication Service リソース内の左側のメニューにある [キー] オプション > [接続文字列] で確認できます。

   

4. 接続名を指定します。

5. [作成]

   このアクションにより、Communication Services ユーザー ID であるユーザー ID が出力されます。 また、[詳細オプションの表示] をクリックし、[トークン スコープ] を選択すると、指定したスコープのアクセス トークンとその有効期限も出力されます。

   

   

ユーザー アクセス トークンを発行する

Communication Services の ID を取得したら、[Issue a user access token](ユーザー アクセス トークンの発行) アクションを使用してアクセス トークンを発行できます。 以下の手順ではその方法を説明します。

1. 新しいアクションを追加し、検索ボックスに「Communication Services Identity」と入力します。 アクションの一覧から [Issue a user access token](ユーザー アクセス トークンの発行) を選択します。

   

2. これで、前出の「ユーザーを作成する」手順で出力されたユーザー ID を使用できます。

3. トークン スコープを指定します (VoIP またはチャット)。 トークンと認証の詳細については、こちらをご覧ください。

   

これにより、指定したスコープでのアクセス トークンとその有効期限が出力されます。

ユーザー アクセス トークンを取り消す

Communication Services の ID を取得したら、[Revoke a user access token](ユーザー アクセス トークンの取り消し) アクションを使用してアクセス トークンを取り消すことができます。 以下の手順ではその方法を説明します。

1. 新しいアクションを追加し、検索ボックスに「Communication Services Identity」と入力します。 アクションの一覧から [Revoke user access tokens](ユーザー アクセス トークンの取り消し) を選択します。

   

2. ユーザー ID を指定します。

   

これにより、指定したユーザーのユーザー アクセス トークンがすべて取り消されます。このアクションの出力はありません。

ユーザーの削除

Communication Services の ID を取得したら、[Delete a user](ユーザーの削除) アクションを使用してユーザーを削除することができます。 以下の手順ではその方法を説明します。

1. 新しいアクションを追加し、検索ボックスに「Communication Services Identity」と入力します。 アクションの一覧から [ユーザーの削除] を選択します。

   

2. ユーザー ID を指定します。

   

   これにより、指定したユーザーが削除され、そのユーザーのすべてのユーザー アクセス トークンが取り消されます。このアクションの出力はありません。

ロジック アプリをテストする

ワークフローを手動で開始するには、デザイナーのツール バーの [実行] を選択します。 このワークフローでは、ユーザーを作成し、そのユーザーのアクセス トークンを発行してから削除し、ユーザーを削除する必要があります。 詳細については、ワークフローを実行する方法を確認してください。 ワークフローが正常に実行された後で、これらのアクションの出力を確認できます。

監視とメトリックに ID を使用する

ユーザー ID は、Azure Monitor によって収集されるログとメトリックのプライマリ キーとして機能することを目的としています。 たとえば、特定のユーザーのすべての呼び出しを表示する場合は、特定の Azure Communication Services ID (または複数の ID) を単一のユーザーにマップするように認証を設定する必要があります。

詳細については、認証の概念、ログ分析による呼び出しの診断、使用可能なメトリックに関するページを参照してください。

リソースをクリーンアップする

Communication Services サブスクリプションをクリーンアップして削除するには、リソースまたはリソース グループを削除します。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。 詳細については、「Communication Services リソースの作成と管理」の「リソースのクリーン アップ」セクションを参照してください。

ロジック アプリ ワークフローおよび関連するリソースのクリーンアップについては、Azure Logic Apps リソースのクリーンアップ方法に関するセクションを参照してください。

次のステップ

このクイックスタートでは、次の方法について学習しました。

• アクセス トークンを発行する
• ID を管理する

音声通話をアプリに追加する

次の記事もご覧ください。

• 認証について学習する
• チャットをアプリに追加する
• クライアントとサーバーのアーキテクチャについて学習する
• Trusted Authentication サービスのヒーロー サンプルをデプロイする

次の手順

このクイックスタートでは、Azure Communication Services Identity コネクタを使用して、ユーザーの作成、ユーザーの削除、ユーザーへのアクセス トークンの発行、ユーザー アクセス トークンの取り消しを行う方法について説明しました。 詳細については、Azure Communication Services Identity コネクタのドキュメントを参照してください。

他のコネクタでトークンがどのように使用されるかを確認するには、Azure Communication Services を使用して Power Automate からチャット メッセージを送信する方法を参照してください。

Azure Communication Services Email コネクタを使用して電子メールを送信する方法については、「Azure Communication Services を使用して Power Automate で電子メール メッセージを送信する」を参照してください。