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

适用于 Java 的 Azure 通信标识客户端库 - 版本 1.4.11

项目
10/21/2023

标识包用于管理Azure 通信服务的用户和令牌。

源代码 | 包 (Maven) | API 参考文档 | 产品文档

入门

先决条件

Azure 订阅。免费创建帐户。
Java 开发工具包 (JDK) 8 或更高版本。
Apache Maven。
通信服务资源。可以使用 Azure 门户或Azure PowerShell对其进行设置。

添加包

包括 BOM 文件

请将 azure-sdk-bom 包含在项目中，以依赖于库的正式发布 (GA) 版本。在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<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>

验证客户端

有两种形式的身份验证可以使用标识 SDK：

Azure Active Directory 令牌身份验证

DefaultAzureCredential对象必须通过 credential () 函数传递到 CommunicationIdentityClientBuilder 。还必须分别通过 endpoint () 和 httpClient () 函数设置终结点和 httpClient。

AZURE_CLIENT_SECRET创建 AZURE_CLIENT_ID DefaultAzureCredential 对象需要和 AZURE_TENANT_ID 环境变量。

// 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 身份验证

标识使用具有资源访问密钥的 HMAC 身份验证。访问密钥可用于创建 AzureKeyCredential，并通过 credential () 函数提供给 CommunicationIdentityClientBuilder 。还必须分别通过 endpoint () 和 httpClient () 函数设置终结点和 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());

还可以通过自定义过期时间来创建通信标识访问令牌。可以将令牌配置为在一小时或 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());

在单个请求中创建新用户和令牌

为方便起见，使用 createUserAndToken 创建新用户，并通过一个函数调用颁发令牌。这转换为单个 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());

还可以在此处指定通信标识访问令牌的过期时间。可以将令牌配置为在一小时或 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 访问令牌交换为通信标识访问令牌

getTokenForTeamsUser使用函数将 Teams 用户的 Azure AD 访问令牌交换为新的通信标识访问令牌。

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

后续步骤

请查看示例目录，获取有关如何使用此库管理标识和令牌的详细示例。

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

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

曝光数

通过