Biblioteca de clientes da Identidade de Comunicação do Azure para Java – versão 1.4.11

Artigo
10/21/2023

O pacote de identidade é usado para gerenciar usuários e tokens para Serviços de Comunicação do Azure.

Código-fonte | Pacote (Maven) | Documentação | de referência da API Documentação do produto

Introdução

Pré-requisitos

Uma assinatura do Azure. Crie uma conta gratuitamente.
JDK (Java Development Kit) versão 8 ou superior.
Apache Maven.
Um recurso dos Serviços de Comunicação. Você pode usar o Portal do Azure ou o Azure PowerShell para configurá-lo.

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

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

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-identity</artifactId>
  <version>1.4.11</version>
</dependency>

Autenticar o cliente

Há duas formas de autenticação para usar o SDK de Identidade:

Autenticação de Token do Azure Active Directory

Um DefaultAzureCredential objeto deve ser passado para o CommunicationIdentityClientBuilder por meio da função credential(). Ponto de extremidade e httpClient também devem ser definidos por meio das funções endpoint() e httpClient(), respectivamente.

AZURE_CLIENT_SECRET, AZURE_CLIENT_ID e AZURE_TENANT_ID variáveis de ambiente são necessárias para criar um objeto 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();

Autenticação AzureKeyCredential

A identidade usa a autenticação HMAC com a chave de acesso do recurso. A chave de acesso pode ser usada para criar uma AzureKeyCredential e fornecida à CommunicationIdentityClientBuilder por meio da função credential(). Ponto de extremidade e httpClient também devem ser definidos por meio das funções endpoint() e httpClient(), respectivamente.

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

Autenticação de cadeia de conexão

Como alternativa, você pode fornecer todo o cadeia de conexão usando a função connectionString() em vez de fornecer o ponto de extremidade e a chave de acesso.

// You can find your connection string from your resource in the Azure Portal
String connectionString = "<connection_string>";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Principais conceitos

CommunicationIdentityClient e CommunicationIdentityAsyncClient fornecem as funcionalidades para gerenciar usuários e tokens de usuário.

Exemplos

Criando um novo usuário

Use a createUser função para criar um novo usuário. user.getId() obtém a ID exclusiva do usuário que foi criado.

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("User id: " + user.getId());

Obtendo um token para um usuário existente

Use a getToken função para obter um token para um usuário existente. A função também usa uma lista de CommunicationTokenScope. As opções de escopo incluem:

chat (Chat)
voip (Voz sobre 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());

Também é possível criar um token de acesso à Identidade de Comunicação personalizando o tempo de expiração. O token pode ser configurado para expirar em apenas uma hora ou até 24 horas. O tempo de expiração padrão é de 24 horas.

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

Criar um novo usuário e token em uma única solicitação

Para conveniência, use createUserAndToken para criar um novo usuário e emitir um token com uma chamada de função. Isso se traduz em uma única solicitação da Web em vez de criar um usuário primeiro e, em seguida, emitir um token.

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

Aqui também é possível especificar o tempo de expiração para o token de acesso da Identidade de Comunicação. O token pode ser configurado para expirar em apenas uma hora ou até 24 horas. O tempo de expiração padrão é de 24 horas.

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

Revogando todos os tokens para um usuário existente

Use a revokeTokens função para revogar todos os tokens emitidos de um usuário.

// revoke tokens issued for the specified user
communicationIdentityClient.revokeTokens(user);

Excluir um usuário

Use a deleteUser função para excluir um usuário.

// delete a previously created user
communicationIdentityClient.deleteUser(user);

Trocando Azure AD token de acesso de um usuário do Teams por um token de acesso da Identidade de Comunicação

Use a getTokenForTeamsUser função para trocar um token de acesso Azure AD de um usuário do Teams por um novo token de acesso da Identidade de Comunicação.

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

Solução de problemas

Todas as operações de serviço de token de usuário lançarão uma exceção em caso de falha.

try {
    CommunicationUserIdentifier user = communicationIdentityClient.createUser();
} catch (RuntimeException ex) {
    System.out.println(ex.getMessage());
}

Próximas etapas

Examine o diretório de exemplos para obter exemplos detalhados de como usar essa biblioteca para gerenciar identidades e tokens.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Partilhar via