.NET 用 Azure Communication Identity クライアント ライブラリ - バージョン 1.2.0

  • [アーティクル]

Azure Communication Identity では、Azure Communication Servicesのトークンを管理しています。

ソースコード | 製品ドキュメント | サンプル

作業の開始

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

NuGet を使用して .NET 用の Azure Communication Identity クライアント ライブラリをインストールします。

dotnet add package Azure.Communication.Identity

前提条件

このパッケージを使用するには、 Azure サブスクリプション と Communication Service リソース が必要です。

新しい Communication Service を作成するには、Azure Portal、Azure PowerShell、または .NET 管理クライアント ライブラリを使用できます。

クライアントを認証する

ID クライアントは、 Azure Portal の Azure Communication Resources から取得した接続文字列を使用して認証できます。

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);

または、 Azure Portal で Azure Communication Resources から取得したエンドポイントとアクセス キーを使用することもできます。

var endpoint = new Uri("https://my-resource.communication.azure.com");
var accessKey = "<access_key>";
var client = new CommunicationIdentityClient(endpoint, new AzureKeyCredential(accessKey));

クライアントには、有効な Active Directory トークンを使用して認証するオプションもあります。

var endpoint = new Uri("https://my-resource.communication.azure.com");
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(endpoint, tokenCredential);

主要な概念

CommunicationIdentityClient には、ユーザー アクセス トークンの作成と取り消しという、ユーザー アクセス トークンを管理するための機能が用意されています。

スレッド セーフ

すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、スレッド間であっても、クライアント インスタンスの再利用に関する推奨事項が常に安全になります。

その他の概念

クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間

例

新しいユーザーの作成

Response<CommunicationUserIdentifier> userResponse = await client.CreateUserAsync();
CommunicationUserIdentifier user = userResponse.Value;
Console.WriteLine($"User id: {user.Id}");

既存のユーザーのトークンの取得

Response<AccessToken> tokenResponse = await client.GetTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat });
string token = tokenResponse.Value.Token;
DateTimeOffset expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"Token: {token}");
Console.WriteLine($"Expires On: {expiresOn}");

また、有効期限をカスタマイズして、コミュニケーション ID アクセス トークンを作成することもできます。 トークンの有効期間は [1,24] 時間の範囲内である必要があります。 指定しない場合は、既定値の 24 時間が使用されます。

TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
Response<AccessToken> tokenResponse = await client.GetTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat }, tokenExpiresIn);
string token = tokenResponse.Value.Token;
DateTimeOffset expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"Token: {token}");
Console.WriteLine($"Expires On: {expiresOn}");

同じ要求でのユーザーとトークンの作成

Response<CommunicationUserIdentifierAndToken> response = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.Chat });
var (user, token) = response.Value;
Console.WriteLine($"User id: {user.Id}");
Console.WriteLine($"Token: {token.Token}");

また、有効期限をカスタマイズして、コミュニケーション ID アクセス トークンを作成することもできます。 トークンの有効期間は [1,24] 時間の範囲内である必要があります。 指定しない場合は、既定値の 24 時間が使用されます。

TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
Response<CommunicationUserIdentifierAndToken> response = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.Chat }, tokenExpiresIn);
var (user, token) = response.Value;
Console.WriteLine($"User id: {user.Id}");
Console.WriteLine($"Token: {token.Token}");

ユーザーのトークンを取り消す

ユーザーのトークンが侵害された場合、または取り消す必要がある場合:

Response revokeResponse = await client.RevokeTokensAsync(user);

ユーザーの削除

Response deleteResponse = await client.DeleteUserAsync(user);

Teams ユーザーの Azure AD アクセス トークンを通信 ID アクセス トークンと交換する

を CommunicationIdentityClient 使用して、Teams ユーザーの Azure AD アクセス トークンを、有効期限が一致する新しいコミュニケーション ID アクセス トークンと交換できます。

関数は GetTokenForTeamsUser 、オプション バッグにラップされた次のパラメーターを GetTokenForTeamsUserOptions 受け入れます。

  • teamsUserAadToken Teams ユーザーの Azure Active Directory アクセス トークン
  • clientId Azure AD アクセス トークンの appId 要求に対して検証される Azure AD アプリケーションのクライアント ID
  • userObjectId Azure AD アクセス トークンの OID 要求に対して検証される Azure AD ユーザー (Teams ユーザー) のオブジェクト ID
Response<AccessToken> tokenResponse = await client.GetTokenForTeamsUserAsync(new GetTokenForTeamsUserOptions(teamsUserAadToken, clientId, userObjectId));
string token = tokenResponse.Value.Token;
Console.WriteLine($"Token: {token}");

トラブルシューティング

すべてのユーザー トークン サービス操作は、失敗時に RequestFailedException をスローします。

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);

try
{
    Response<CommunicationUserIdentifier> response = await client.CreateUserAsync();
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.Message);
}

次のステップ

コミュニケーション ユーザー アクセス トークンの詳細を参照してください

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。