Azure.Communication.Identity 1.3.1

为 .NET 提供的 Azure 通信身份客户端库

Azure 通信身份管理 Azure 通信服务的令牌。

源代码 | 产品文档 | 示例

入门

安装包

使用 NuGet 安装 Azure 通信身份 .NET 客户端库

dotnet add package Azure.Communication.Identity

先决条件

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

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

验证客户端

可以使用从Azure Portal获取的 Azure 通讯资源连接字符串来验证身份客户端。

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

或者，你也可以使用从Azure Portal获取的端点和访问密钥。

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

GetToken 函数接受一个 CommunicationTokenScope 列表。作用域选项包括

• Chat（用于完全访问 Chat API）
• VoIP（用于完全访问 Calling API）
• ChatJoin（访问 Chat API，但没有创建、删除或更新聊天线程的授权）
• ChatJoinLimited（比 ChatJoin 更有限制的版本，不允许添加或删除参与者）
• VoIPJoin（访问 Calling API，但没有开始新的呼叫的授权）

还可以通过自定义过期时间来创建具有通信身份访问令牌。令牌的有效期必须在 [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 应用程序的 Client ID
• userObjectId Azure AD 用户（Teams 用户）的 Object ID，将与其在 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。

本项目已采纳微软开源行为准则。更多信息请参阅行为准则常见问题或联系[email protected]，如有任何额外问题或意见。