Java 用 Azure Communication Identity クライアント ライブラリ - バージョン 1.4.11
ID パッケージは、Azure Communication Servicesのユーザーとトークンを管理するために使用されます。
ソースコード | パッケージ (Maven) | API リファレンス ドキュメント | 製品ドキュメント
作業の開始
前提条件
- Azure サブスクリプション。 無料でアカウントを作成できます。
- Java Development Kit (JDK) バージョン 8 以降。
- Apache Maven。
- Communication Services リソース。 Azure Portal またはAzure PowerShellを使用して設定できます。
パッケージを組み込む
BOM ファイルを含める
ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。 次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-sdk-bom</artifactId>
<version>{bom_version_to_target}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
次に、バージョン タグのない依存関係セクションに直接依存関係を含めます。
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-identity</artifactId>
</dependency>
</dependencies>
直接依存関係を含める
BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-identity</artifactId>
<version>1.4.11</version>
</dependency>
クライアントを認証する
Identity SDK を使用する認証には、次の 2 つの形式があります。
Azure Active Directory トークン認証
オブジェクトは DefaultAzureCredential credential() 関数を介して に CommunicationIdentityClientBuilder 渡す必要があります。 Endpoint と httpClient は、それぞれ endpoint() 関数と httpClient() 関数を使用して設定する必要があります。
AZURE_CLIENT_SECRET、 AZURE_CLIENT_ID および AZURE_TENANT_ID 環境変数は、DefaultAzureCredential オブジェクトを作成するために必要です。
// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
.endpoint(endpoint)
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
AzureKeyCredential 認証
ID は、リソース アクセス キーで HMAC 認証を使用します。
アクセス キーを使用して AzureKeyCredential を作成し、credential() 関数を介して に CommunicationIdentityClientBuilder 提供できます。 Endpoint と httpClient は、それぞれ endpoint() 関数と httpClient() 関数を使用して設定する必要があります。
// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("<access-key>");
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
.endpoint(endpoint)
.credential(keyCredential)
.buildClient();
接続文字列認証
または、エンドポイントとアクセス キーを指定する代わりに、connectionString() 関数を使用して接続文字列全体を指定することもできます。
// You can find your connection string from your resource in the Azure Portal
String connectionString = "<connection_string>";
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
.connectionString(connectionString)
.buildClient();
主要な概念
CommunicationIdentityClient ユーザーと CommunicationIdentityAsyncClient ユーザー トークンを管理するための機能を提供します。
例
新しいユーザーの作成
関数を createUser 使用して新しいユーザーを作成します。 user.getId() は、作成されたユーザーの一意の ID を取得します。
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("User id: " + user.getId());
既存のユーザーのトークンの取得
関数を getToken 使用して、既存のユーザーのトークンを取得します。 関数は の一覧 CommunicationTokenScopeも受け取ります。 スコープ オプションには、次のものが含まれます。
chat(チャット)voip(ボイス オーバー IP)
// Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
AccessToken userToken = communicationIdentityClient.getToken(user, scopes);
System.out.println("User token value: " + userToken.getToken());
System.out.println("Expires at: " + userToken.getExpiresAt());
また、有効期限をカスタマイズすることで、通信 ID アクセス トークンを作成することもできます。 トークンは、少しでも 1 時間でも 24 時間でも期限切れするように構成できます。 既定の有効期限は 24 時間です。
// Define a list of Communication Identity access token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
// Set custom validity period of the Communication Identity access token within [1,24]
// hours range. If not provided, the default value of 24 hours will be used.
Duration tokenExpiresIn = Duration.ofHours(1);
AccessToken userToken = communicationIdentityClient.getToken(user, scopes, tokenExpiresIn);
System.out.println("User token value: " + userToken.getToken());
System.out.println("Expires at: " + userToken.getExpiresAt());
1 つの要求で新しいユーザーとトークンを作成する
便宜上、 を使用 createUserAndToken して新しいユーザーを作成し、1 つの関数呼び出しでトークンを発行します。 これは、最初にユーザーを作成してからトークンを発行するのではなく、単一の Web 要求に変換されます。
// Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
System.out.println("User id: " + result.getUser().getId());
System.out.println("User token value: " + result.getUserToken().getToken());
ここでは、通信 ID アクセス トークンの有効期限を指定することもできます。 トークンは、少しでも 1 時間でも 24 時間でも期限切れするように構成できます。 既定の有効期限は 24 時間です。
// Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
// Set custom validity period of the Communication Identity access token within [1,24]
// hours range. If not provided, the default value of 24 hours will be used.
Duration tokenExpiresIn = Duration.ofHours(1);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes, tokenExpiresIn);
System.out.println("User id: " + result.getUser().getId());
System.out.println("User token value: " + result.getUserToken().getToken());
既存のユーザーのすべてのトークンを取り消す
関数を revokeTokens 使用して、ユーザーのすべての発行済みトークンを取り消します。
// revoke tokens issued for the specified user
communicationIdentityClient.revokeTokens(user);
ユーザーの削除
関数を deleteUser 使用してユーザーを削除します。
// delete a previously created user
communicationIdentityClient.deleteUser(user);
Teams ユーザーの Azure AD アクセス トークンを通信 ID アクセス トークンと交換する
関数を getTokenForTeamsUser 使用して、Teams ユーザーの Azure AD アクセス トークンを新しいコミュニケーション ID アクセス トークンと交換します。
String clientId = "<Client ID of an Azure AD application>";
String userObjectId = "<Object ID of an Azure AD user (Teams User)>";
GetTokenForTeamsUserOptions options = new GetTokenForTeamsUserOptions(teamsUserAadToken, clientId, userObjectId);
AccessToken accessToken = communicationIdentityClient.getTokenForTeamsUser(options);
System.out.println("User token value: " + accessToken.getToken());
System.out.println("Expires at: " + accessToken.getExpiresAt());
トラブルシューティング
すべてのユーザー トークン サービス操作では、エラー時に例外がスローされます。
try {
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
} catch (RuntimeException ex) {
System.out.println(ex.getMessage());
}
次の手順
このライブラリを使用して ID とトークンを管理する方法の詳細な例については、 サンプル ディレクトリを参照してください。
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。
pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。
このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。
