Java 用 Azure Communication Identity クライアント ライブラリ - バージョン 1.4.11

  • [アーティクル]

ID パッケージは、Azure Communication Servicesのユーザーとトークンを管理するために使用されます。

ソースコード | パッケージ (Maven) | API リファレンス ドキュメント | 製品ドキュメント

作業の開始

前提条件

パッケージを組み込む

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 宛てに質問またはコメントをお送りください。

インプレッション数