你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 通信标识客户端库 - 版本 1.2.0

项目
04/18/2023

Azure 通信标识正在管理Azure 通信服务的令牌。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 通信标识客户端库：

dotnet add package Azure.Communication.Identity

先决条件

需要 Azure 订阅和通信服务资源才能使用此包。

若要创建新的通信服务，可以使用 Azure 门户、Azure PowerShell或 .NET 管理客户端库。

验证客户端

可以使用从 Azure 门户中的 Azure 通信资源获取的连接字符串对标识客户端进行身份验证。

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

或者，使用从 Azure 门户中的 Azure 通信资源获取的终结点和访问密钥。

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}");

还可以通过自定义过期时间来创建通信标识访问令牌。令牌的有效期必须在 [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}");

还可以通过自定义过期时间来创建通信标识访问令牌。令牌的有效期必须在 [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 访问令牌交换为通信标识访问令牌

CommunicationIdentityClient可用于将 Teams 用户的 Azure AD 访问令牌交换为具有匹配过期时间的新通信标识访问令牌。

函数 GetTokenForTeamsUser 接受包装到选项包中的 GetTokenForTeamsUserOptions 以下参数：

teamsUserAadToken Teams 用户的 Azure Active Directory 访问令牌
clientId 要根据 Azure AD 访问令牌中的 appId 声明验证的 Azure AD 应用程序的客户端 ID
userObjectId Azure AD 用户的对象 ID (Teams 用户) 针对 Azure AD 访问令牌中的 OID 声明进行验证

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)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过