Quickstart: Criar e gerir fichas de acesso

Os tokens de acesso permitem que Azure Communication Services SDKs autentem diretamente contra Azure Communication Services como uma identidade particular. Terá de criar fichas de acesso se quiser que os seus utilizadores se juntem a uma chamada ou linha de chat dentro da sua aplicação.

Neste arranque rápido, você vai aprender a usar os Azure Communication Services SDKs para criar identidades e gerir os seus tokens de acesso. Para casos de utilização de produção, recomendamos que gere fichas de acesso num serviço do lado do servidor.

Pré-requisitos

Configuração

Adicionar a extensão

Adicione a extensão Azure Communication Services para Azure CLI utilizando o az extension comando.

az extension add --name communication

Iniciar sessão na CLI do Azure

Tens de te inscrever no Azure CLI. Pode iniciar singing no az login comando a partir do terminal e fornecer as suas credenciais.

(Opcional) Utilize operações de identidade do Azure CLI sem passar numa cadeia de ligação

Pode configurar a AZURE_COMMUNICATION_CONNECTION_STRING variável ambiente para utilizar operações de identidade Azure CLI sem ter de usar --connection_string para passar na cadeia de ligação. Para configurar uma variável ambiental, abra uma janela da consola e selecione o seu sistema operativo a partir dos separadores abaixo. Substitua-a <yourConnectionString> pela sua verdadeira cadeia de ligação.

Abra uma janela da consola e introduza o seguinte comando:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Depois de adicionar a variável de ambiente, poderá ter de reiniciar todos os programas em execução que irão precisar de ler a variável de ambiente, incluindo a janela da consola. Por exemplo, se estiver a utilizar o Visual Studio como seu editor, reinicie o Visual Studio antes de executar o exemplo.

Guarde o seu token de acesso numa variável ambiental

Para configurar uma variável ambiental, abra uma janela da consola e selecione o seu sistema operativo a partir dos separadores abaixo. Substitua-o <yourAccessToken> pelo seu token de acesso real.

Abra uma janela da consola e introduza o seguinte comando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Depois de adicionar a variável de ambiente, poderá ter de reiniciar todos os programas em execução que irão precisar de ler a variável de ambiente, incluindo a janela da consola. Por exemplo, se estiver a utilizar o Visual Studio como seu editor, reinicie o Visual Studio antes de executar o exemplo.

Operações

Criar uma identidade

Para criar fichas de acesso, precisa de uma identidade. Azure Communication Services mantém um diretório de identidade leve para este fim. Utilize o user create comando para criar uma nova entrada no diretório com um único Id. A identidade é necessária mais tarde para a emissão de fichas de acesso.

az communication identity user create --connection-string "<yourConnectionString>"
  • Substitua-a <yourConnectionString> pela sua cadeia de ligação.

Criar uma identidade e emitir um símbolo de acesso no mesmo pedido

Executar o seguinte comando para criar uma identidade dos Serviços de Comunicação e emitir um token de acesso para ele ao mesmo tempo. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas em Autenticação para Azure Communication Services.

az communication identity token issue --scope chat --connection-string "<yourConnectionString>"

Faça esta substituição no código:

  • Substitua-a <yourConnectionString> pela sua cadeia de ligação.

Emitir ficha de acesso

Executar o seguinte comando para emitir um token de acesso para a sua identidade de Serviços de Comunicação. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas em Autenticação para Azure Communication Services.

az communication identity token issue --scope chat --user "<userId>" --connection-string "<yourConnectionString>"

Faça esta substituição no código:

  • Substitua-a <yourConnectionString> pela sua cadeia de ligação.
  • Substitua-o <userId> pelo seu userId.

Os tokens de acesso são credenciais de curta duração que precisam de ser reeditadas. Não fazê-lo pode causar uma perturbação da experiência dos utilizadores da sua aplicação. A expires_on propriedade de resposta indica a vida útil do token de acesso.

Emitir token de acesso com vários âmbitos

Executar o seguinte comando para emitir um token de acesso com vários âmbitos para a sua identidade de Serviços de Comunicação. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas no modelo Identidade.

az communication identity token issue --scope chat voip --user "<userId>" --connection-string "<yourConnectionString>"

Faça esta substituição no código:

  • Substitua-a <yourConnectionString> pela sua cadeia de ligação.
  • Substitua-o <userId> pelo seu userId.

Os tokens de acesso são credenciais de curta duração que precisam de ser reeditadas. Não fazê-lo pode causar uma perturbação da experiência dos utilizadores da sua aplicação. A expires_on propriedade de resposta indica a vida útil do token de acesso.

Troque um token de acesso Azure AD do Utilizador das Equipas por um token de acesso à identidade de comunicação

Utilize o token get-for-teams-user comando para emitir um token de acesso para o utilizador das Equipas que pode ser utilizado com os Azure Communication Services SDKs.

az communication identity token get-for-teams-user --aad-token "<yourAadToken>" --client "<yourAadApplication>" --aad-user "<yourAadUser>" --connection-string "<yourConnectionString>"

Faça esta substituição no código:

  • Substitua-a <yourConnectionString> pela sua cadeia de ligação.
  • Substitua-o pelo <yourAadUser> seu utilizador Azure Ative DirectoryId.
  • Substitua-o pelo <yourAadApplication> Id de aplicação do Azure Ative.
  • Substitua <yourAadToken> o seu token de acesso Azure Ative.

Revogar fichas de acesso

Pode ocasionalmente precisar de revogar explicitamente um sinal de acesso. Por exemplo, o faria quando os utilizadores da aplicação alterassem a palavra-passe que utilizam para autenticar o seu serviço. O token revoke comando invalida todos os tokens de acesso ativo que foram emitidos para a identidade.

az communication identity token revoke --user "<userId>" --connection-string "<yourConnectionString>"

Faça esta substituição no código:

  • Substitua-a <yourConnectionString> pela sua cadeia de ligação.
  • Substitua-o <userId> pelo seu userId.

Excluir uma identidade

Quando elimina uma identidade, revoga todos os tokens de acesso ativo e impede a emissão posterior de fichas de acesso para a identidade. Ao fazê-lo, remove também todo o conteúdo persistido que está associado à identidade.

az communication identity user delete --user "<userId>" --connection-string "<yourConnectionString>"

Faça esta substituição no código:

  • Substitua-a <yourConnectionString> pela sua cadeia de ligação.
  • Substitua-o <userId> pelo seu userId.

Pré-requisitos

Código final

Encontre o código finalizado para este arranque rápido no GitHub.

Configurar o ambiente

Criar uma nova aplicação C#

Numa janela de pedido de comando, como cmd, PowerShell ou Bash, executar o dotnet new comando para criar uma nova aplicação de consola com o nome AccessTokensQuickstart. Este comando cria um projeto "Hello World" C# com um único ficheiro de origem, Programa.cs.

dotnet new console -o AccessTokensQuickstart

Mude o seu diretório para a pasta de aplicação recém-criada e use o dotnet build comando para compilar a sua aplicação.

cd AccessTokensQuickstart
dotnet build

Deve ser apresentada uma saída simples de "Hello World". Se for, a sua configuração está a funcionar corretamente e pode começar a escrever o seu código específico Azure Communication Services.

Instale o pacote

Enquanto estiver no diretório de aplicações, instale a biblioteca Azure Communication Services Identity para o pacote .NET utilizando o dotnet add package comando.

dotnet add package Azure.Communication.Identity --version 1.0.0

Configurar o quadro de aplicações

No diretório do projeto, faça o seguinte:

  1. Abra o ficheiro .cs Programa num editor de texto.
  2. Adicione uma using diretiva para incluir o espaço de Azure.Communication.Identity nome.
  3. Atualize a declaração de Main método para suportar o código assínc.

Para começar, execute o seguinte código:

using System;
using Azure;
using Azure.Core;
using Azure.Communication.Identity;

namespace AccessTokensQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Access Tokens Quickstart");

            // Quickstart code goes here
        }
    }
}

Autenticar o cliente

Inicialize CommunicationIdentityClient com a sua cadeia de ligação. O seguinte código, que se adiciona ao Main método, recupera a cadeia de ligação para o recurso a partir de uma variável ambiental chamada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para mais informações, consulte a secção "Armazenar a sua cadeia de ligação" da Criar e gerir os recursos dos Serviços de Comunicação.

// This code demonstrates how to retrieve your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
var client = new CommunicationIdentityClient(connectionString);

Em alternativa, pode separar a chave de ponta e acesso executando o seguinte código:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
string endpoint = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ENDPOINT");
string accessKey = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ACCESSKEY");
var client = new CommunicationIdentityClient(new Uri(endpoint), new AzureKeyCredential(accessKey));

Se já criou uma aplicação Azure Ative Directory (Azure AD), pode autenticar utilizando Azure AD.

TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);

Criar uma identidade

Para criar fichas de acesso, precisa de uma identidade. Azure Communication Services mantém um diretório de identidade leve para este fim. Utilize o createUser método para criar uma nova entrada no diretório com um único Id. A identidade é necessária mais tarde para a emissão de fichas de acesso.

var identityResponse = await client.CreateUserAsync();
var identity = identityResponse.Value;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");

Guarde a identidade recebida com mapeamento para os utilizadores da sua aplicação (por exemplo, armazenando-a na base de dados do seu servidor de aplicações).

Emitir fichas de acesso

Depois de ter uma identidade dos Serviços de Comunicação, utilize o GetToken método para emitir um token de acesso para o mesmo. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas no modelo Identidade. Também pode construir uma nova instância baseada numa representação de communicationUser cordas de uma identidade do Serviço de Comunicação Azure.

// Issue an access token with the "voip" scope for an identity
var tokenResponse = await client.GetTokenAsync(identity, scopes: new [] { CommunicationTokenScope.VoIP });

// Get the token from the response
var token =  tokenResponse.Value.Token;
var expiresOn = tokenResponse.Value.ExpiresOn;

// Write the token details to the screen
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Os tokens de acesso são credenciais de curta duração que precisam de ser reeditadas. Não fazê-lo pode causar uma perturbação da experiência dos utilizadores da sua aplicação. A expiresOn propriedade indica a vida útil do token de acesso.

Criar uma identidade e emitir um símbolo no mesmo pedido

Pode utilizar o CreateUserAndTokenAsync método para criar uma identidade dos Serviços de Comunicação e emitir um sinal de acesso ao mesmo tempo. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas em Autenticação para Azure Communication Services.

// Issue an identity and an access token with the "voip" scope for the new identity
var identityAndTokenResponse = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.VoIP });

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.Value.User;
var token = identityAndTokenResponse.Value.AccessToken.Token;
var expiresOn = identityAndTokenResponse.Value.AccessToken.ExpiresOn;

// Print the details to the screen
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Atualizar tokens de acesso

Para refrescar um token de acesso, passe uma instância do CommunicationUserIdentifier objeto para GetTokenAsync. Se guardou isto Id e precisa de criar um novo CommunicationUserIdentifier, pode fazê-lo passando o seu armazenado Id no construtor da CommunicationUserIdentifier seguinte forma:

var identityToRefresh = new CommunicationUserIdentifier(identity.Id);
var tokenResponse = await client.GetTokenAsync(identityToRefresh, scopes: new [] { CommunicationTokenScope.VoIP });

Revogar fichas de acesso

Pode ocasionalmente precisar de revogar explicitamente um sinal de acesso. Por exemplo, o faria quando os utilizadores da aplicação alterassem a palavra-passe que utilizam para autenticar o seu serviço. O RevokeTokensAsync método invalida todos os tokens de acesso ativo que foram emitidos para a identidade.

await client.RevokeTokensAsync(identity);
Console.WriteLine($"\nSuccessfully revoked all access tokens for identity with ID: {identity.Id}");

Excluir uma identidade

Quando elimina uma identidade, revoga todos os tokens de acesso ativo e impede a emissão posterior de fichas de acesso para a identidade. Ao fazê-lo, remove também todo o conteúdo persistido que está associado à identidade.

await client.DeleteUserAsync(identity);
Console.WriteLine($"\nDeleted the identity with ID: {identity.Id}");

Executar o código

Quando terminar de criar o token de acesso, pode executar a aplicação a partir do seu diretório de aplicações utilizando o dotnet run comando.

dotnet run

A saída da aplicação descreve cada ação concluída:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Pré-requisitos

Código final

Encontre o código finalizado para este arranque rápido no GitHub.

Configurar o ambiente

Criar uma nova aplicação Node.js

Numa janela terminal ou command prompt, crie um novo diretório para a sua aplicação e, em seguida, abra-o.

mkdir access-tokens-quickstart && cd access-tokens-quickstart

Corra npm init -y para criar um ficheiro package.json com definições predefinições.

npm init -y

Instale o pacote

Utilize o npm install comando para instalar o SDK de identidade Azure Communication Services para JavaScript.

npm install @azure/communication-identity --save

A --save opção lista a biblioteca como uma dependência no seu ficheiro package.json .

Configurar o quadro de aplicações

  1. Crie um ficheiro nomeado issue-access-token.js no diretório do projeto e adicione o seguinte código:

    const { CommunicationIdentityClient } = require('@azure/communication-identity');
    
    const main = async () => {
      console.log("Azure Communication Services - Access Tokens Quickstart")
    
      // Quickstart code goes here
    };
    
    main().catch((error) => {
      console.log("Encountered an error");
      console.log(error);
    })
    

Autenticar o cliente

Instantaneamente CommunicationIdentityClient com a sua cadeia de ligação. O seguinte código, que se adiciona ao Main método, recupera a cadeia de ligação para o recurso a partir de uma variável ambiental chamada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para mais informações, consulte a secção "Armazenar a sua cadeia de ligação" da Criar e gerir os recursos dos Serviços de Comunicação.

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(connectionString);

Em alternativa, pode separar a chave de ponta e acesso executando o seguinte código:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const accessKey = process.env["COMMUNICATION_SERVICES_ACCESSKEY"];

// Create the credential
const tokenCredential = new AzureKeyCredential(accessKey);

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential)

Se já criou uma aplicação Azure Ative Directory (Azure AD), pode autenticar utilizando Azure AD.

const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const tokenCredential = new DefaultAzureCredential();
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential);

Criar uma identidade

Para criar fichas de acesso, precisa de uma identidade. Azure Communication Services mantém um diretório de identidade leve para este fim. Utilize o createUser método para criar uma nova entrada no diretório com um único Id. A identidade é necessária mais tarde para a emissão de fichas de acesso.

let identityResponse = await identityClient.createUser();
console.log(`\nCreated an identity with ID: ${identityResponse.communicationUserId}`);

Guarde a identidade recebida com mapeamento para os utilizadores da sua aplicação (por exemplo, armazenando-a na base de dados do seu servidor de aplicações).

Emitir fichas de acesso

Utilize o getToken método para emitir um sinal de acesso para a sua identidade de Serviços de Comunicação. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas no modelo Identidade. Também pode construir um novo exemplo de uma communicationUser com base numa representação de cordas da identidade do Serviço de Comunicação Azure.

// Issue an access token with the "voip" scope for an identity
let tokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

// Get the token and its expiration date from the response
const { token, expiresOn } = tokenResponse;

// Print the expiration date and token to the screen
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Os tokens de acesso são credenciais de curta duração que precisam de ser reeditadas. Não fazê-lo pode causar uma perturbação da experiência dos utilizadores da sua aplicação. A expiresOn propriedade indica a vida útil do token de acesso.

Criar uma identidade e emitir um símbolo numa chamada de método

Pode utilizar o createUserAndToken método para criar uma identidade dos Serviços de Comunicação e emitir um sinal de acesso ao mesmo tempo. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Mais uma vez, cria-se com o voip âmbito.

// Issue an identity and an access token with the "voip" scope for the new identity
let identityTokenResponse = await identityClient.createUserAndToken(["voip"]);

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;

// print these details to the screen
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Atualizar tokens de acesso

À medida que as fichas expiram, terás periodicamente de os refrescar. Refrescante é fácil ligar getToken novamente com a mesma identidade que foi usada para emitir os tokens. Também terá de fornecer as scopes fichas renovadas.

// Value of identityResponse represents the Azure Communication Services identity stored during identity creation and then used to issue the tokens being refreshed
let refreshedTokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

Revogar fichas de acesso

Pode ocasionalmente precisar de revogar um símbolo de acesso. Por exemplo, o faria quando os utilizadores da aplicação alterassem a palavra-passe que utilizam para autenticar o seu serviço. O revokeTokens método invalida todos os tokens de acesso ativo que foram emitidos para a identidade.

await identityClient.revokeTokens(identityResponse);

console.log(`\nSuccessfully revoked all access tokens for identity with ID: ${identityResponse.communicationUserId}`);

Excluir uma identidade

Quando elimina uma identidade, revoga todos os tokens de acesso ativo e impede a emissão posterior de fichas de acesso para a identidade. Ao fazê-lo, remove também todo o conteúdo persistido que está associado à identidade.

await identityClient.deleteUser(identityResponse);

console.log(`\nDeleted the identity with ID: ${identityResponse.communicationUserId}`);

Executar o código

A partir de um pedido de consola, vá ao diretório que contém o ficheiro issue-access-token.js e, em seguida, execute o seguinte node comando para executar a aplicação:

node ./issue-access-token.js

A saída da aplicação descreve cada ação concluída:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Pré-requisitos

Código final

Encontre o código finalizado para este arranque rápido no GitHub.

Configurar o ambiente

Criar uma aplicação Python nova

  1. Numa janela terminal ou command prompt, crie um novo diretório para a sua aplicação e, em seguida, abra-o.

    mkdir access-tokens-quickstart && cd access-tokens-quickstart
    
  2. Use um editor de texto para criar um ficheiro chamado issue-access-tokens.py no diretório de raiz do projeto e adicione a estrutura para o programa, incluindo o manuseamento básico de exceções. Irá adicionar todo o código fonte para este arranque rápido a este ficheiro nas secções que se seguem.

    import os
    from azure.communication.identity import CommunicationIdentityClient, CommunicationUserIdentifier
    
    try:
       print("Azure Communication Services - Access Tokens Quickstart")
       # Quickstart code goes here
    except Exception as ex:
       print("Exception:")
       print(ex)
    

Instale o pacote

Enquanto ainda estiver no diretório de aplicações, instale o pacote Azure Communication Services Identity SDK para Python utilizando o pip install comando.

pip install azure-communication-identity

Autenticar o cliente

Instantiizar a CommunicationIdentityClient com a sua cadeia de ligação. O seguinte código, que adiciona ao try bloco, recupera a cadeia de ligação para o recurso a partir de uma variável ambiental chamada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para mais informações, consulte a secção "Armazenar a sua cadeia de ligação" da Criar e gerir os recursos dos Serviços de Comunicação.

# This code demonstrates how to retrieve your connection string
# from an environment variable.
connection_string = os.environ["COMMUNICATION_SERVICES_CONNECTION_STRING"]

# Instantiate the identity client
client = CommunicationIdentityClient.from_connection_string(connection_string)

Em alternativa, se já criou uma aplicação Azure Ative Directory (Azure AD), pode autenticar utilizando Azure AD.

endpoint = os.environ["COMMUNICATION_SERVICES_ENDPOINT"]
client = CommunicationIdentityClient(endpoint, DefaultAzureCredential())

Criar uma identidade

Para criar fichas de acesso, precisa de uma identidade. Azure Communication Services mantém um diretório de identidade leve para este fim. Utilize o create_user método para criar uma nova entrada no diretório com um único Id. A identidade é necessária mais tarde para a emissão de fichas de acesso.

identity = client.create_user()
print("\nCreated an identity with ID: " + identity.properties['id'])

Guarde a identidade recebida com mapeamento para os utilizadores da sua aplicação (por exemplo, armazenando-a na base de dados do seu servidor de aplicações).

Emitir fichas de acesso

Utilize o get_token método para emitir um sinal de acesso para a sua identidade de Serviços de Comunicação. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas no modelo Identidade. Também pode construir uma nova instância de parâmetro CommunicationUserIdentifier baseada numa representação de cordas da identidade do Serviço de Comunicação Azure.

# Issue an access token with the "voip" scope for an identity
token_result = client.get_token(identity, ["voip"])
expires_on = token_result.expires_on.strftime("%d/%m/%y %I:%M %S %p")

# Print the details to the screen
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token_result.token)

Os tokens de acesso são credenciais de curta duração que precisam de ser reeditadas. Não fazê-lo pode causar uma perturbação da experiência dos utilizadores da sua aplicação. A expires_on propriedade de resposta indica a vida útil do token de acesso.

Criar uma identidade e emitir um símbolo de acesso no mesmo pedido

Pode utilizar o create_user_and_token método para criar uma identidade dos Serviços de Comunicação e emitir um sinal de acesso ao mesmo tempo. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas em Autenticação para Azure Communication Services.

# Issue an identity and an access token with the "voip" scope for the new identity
identity_token_result = client.create_user_and_token(["voip"])

# Get the token details from the response
identity = identity_token_result[0]
token = identity_token_result[1].token
expires_on = identity_token_result[1].expires_on.strftime("%d/%m/%y %I:%M %S %p")

# Print the details to the screen
print("\nCreated an identity with ID: " + identity.properties['id'])
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token)

Atualizar tokens de acesso

Para refrescar um token de acesso, use o CommunicationUserIdentifier objeto para reeditar um símbolo passando na identidade existente:

# The existingIdentity value represents the Communication Services identity that's stored during identity creation
identity = CommunicationUserIdentifier(existingIdentity)
token_result = client.get_token(identity, ["voip"])

Revogar fichas de acesso

Pode ocasionalmente precisar de revogar explicitamente um sinal de acesso. Por exemplo, o faria quando os utilizadores da aplicação alterassem a palavra-passe que utilizam para autenticar o seu serviço. O revoke_tokens método invalida todos os tokens de acesso ativo que foram emitidos para a identidade.

client.revoke_tokens(identity)
print("\nSuccessfully revoked all access tokens for identity with ID: " + identity.properties['id'])

Excluir uma identidade

Quando elimina uma identidade, revoga todos os tokens de acesso ativo e impede a emissão posterior de fichas de acesso para a identidade. Ao fazê-lo, remove também todo o conteúdo persistido que está associado à identidade.

client.delete_user(identity)
print("\nDeleted the identity with ID: " + identity.properties['id'])

Executar o código

A partir de um pedido de consola, vá ao diretório que contém o ficheiro issue-access-tokens.py e, em seguida, execute o seguinte python comando para executar a aplicação.

python ./issue-access-tokens.py

A saída da aplicação descreve cada ação concluída:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Pré-requisitos

Código final

Encontre o código finalizado para este arranque rápido no GitHub.

Configurar o ambiente

Criar uma nova aplicação Java

Numa janela terminal ou de solicitação de comando, vá ao diretório onde pretende criar a sua aplicação Java. Para gerar um projeto Java a partir do modelo maven-arqueotype-quickstart, executar o seguinte código:

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Você vai notar que a generate tarefa cria um diretório com o mesmo nome que artifactId. Sob este diretório, o diretório src/main/java contém o código fonte do projeto, o diretório src/teste/java contém a fonte de teste, e o ficheiro pom.xml é o Project Object Model do projeto, ou POM. Este ficheiro é utilizado para parâmetros de configuração do projeto.

Instalar os pacotes de Serviços de Comunicação

Abra o ficheiro pom.xml no seu editor de texto. Adicione o seguinte elemento de dependência ao grupo de dependências:

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

Este código instrui Maven a instalar o SDK de identidade de serviços de comunicação, que utilizará mais tarde.

Configurar o quadro de aplicações

No diretório do projeto, faça o seguinte:

  1. Vá ao diretório /src/main/java/com/communication/quickstart .
  2. Abra o ficheiro .java App no seu editor.
  3. Substitua a System.out.println("Hello world!"); declaração.
  4. Adicione import diretivas.

Utilize o seguinte código para começar:

package com.communication.quickstart;

import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.core.credential.*;

import java.io.IOException;
import java.time.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Access Tokens Quickstart");
        // Quickstart code goes here
    }
}

Autenticar o cliente

Instantaneamente com CommunicationIdentityClient a chave de acesso do seu recurso e ponto final. Para mais informações, consulte a secção "Armazenar a sua cadeia de ligação" da Criar e gerir os recursos dos Serviços de Comunicação.

Além disso, pode inicializar o cliente com qualquer cliente HTTP personalizado que implemente a com.azure.core.http.HttpClient interface.

No ficheiro .java App , adicione o seguinte código ao main método:

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
String accessKey = "SECRET";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(new AzureKeyCredential(accessKey))
        .buildClient();

Em vez de fornecer o ponto final e a chave de acesso, pode fornecer toda a cadeia de ligação utilizando o connectionString() método.

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

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

Se já criou uma aplicação Azure Ative Directory (Azure AD), pode autenticar utilizando Azure AD.

String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(credential)
        .buildClient();

Criar uma identidade

Para criar fichas de acesso, precisa de uma identidade. Azure Communication Services mantém um diretório de identidade leve para este fim. Utilize o createUser método para criar uma nova entrada no diretório com um único Id.

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("\nCreated an identity with ID: " + user.getId());

A identidade criada é necessária mais tarde para a emissão de fichas de acesso. Guarde a identidade recebida com mapeamento para os utilizadores da sua aplicação (por exemplo, armazenando-a na base de dados do seu servidor de aplicações).

Emitir fichas de acesso

Utilize o getToken método para emitir um sinal de acesso para a sua identidade de Serviços de Comunicação. O scopes parâmetro define um conjunto de permissões e funções simbólicas de acesso. Para mais informações, consulte a lista de ações apoiadas no modelo Identidade.

No código seguinte, utilize a variável de utilizador que criou no passo anterior para obter um token.

// Issue an access token with the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes);
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'voip' scope that expires at: " + expiresAt + ": " + token);

Criar uma identidade e emitir um símbolo num único pedido

Em alternativa, pode utilizar o método "createUserToken" para criar uma nova entrada no diretório com um token único Id e emitir um token de acesso ao mesmo tempo.

List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
CommunicationUserIdentifier user = result.getUser();
System.out.println("\nCreated a user identity with ID: " + user.getId());
AccessToken accessToken = result.getUserToken();
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'chat' scope that expires at: " + expiresAt + ": " + token);

Os tokens de acesso são credenciais de curta duração que precisam de ser reeditadas. Não fazê-lo pode causar uma perturbação da experiência dos utilizadores da sua aplicação. A expiresAt propriedade indica a vida útil do token de acesso.

Atualizar tokens de acesso

Para refrescar um token de acesso, use o CommunicationUserIdentifier objeto para reeditá-lo:

// existingIdentity represents the Communication Services identity that's stored during identity creation
CommunicationUserIdentifier identity = new CommunicationUserIdentifier(existingIdentity.getId());
AccessToken response = communicationIdentityClient.getToken(identity, scopes);

Revogar um token de acesso

Pode ocasionalmente precisar de revogar explicitamente um sinal de acesso. Por exemplo, o faria quando os utilizadores da aplicação alterassem a palavra-passe que utilizam para autenticar o seu serviço. O revokeTokens método invalida todos os tokens de acesso ativo para um determinado utilizador. No código seguinte, pode utilizar o utilizador previamente criado.

communicationIdentityClient.revokeTokens(user);
System.out.println("\nSuccessfully revoked all access tokens for user identity with ID: " + user.getId());

Excluir uma identidade

Quando elimina uma identidade, revoga todos os tokens de acesso ativo e impede a emissão posterior de fichas de acesso para a identidade. Ao fazê-lo, remove também todo o conteúdo persistido que está associado à identidade.

communicationIdentityClient.deleteUser(user);
System.out.println("\nDeleted the user identity with ID: " + user.getId());

Executar o código

Vá ao diretório que contém o ficheiro pom.xml e, em seguida, compile o projeto utilizando o seguinte mvn comando:

mvn compile

Em seguida, construa o pacote:

mvn package

Execute o seguinte mvn comando para executar a aplicação:

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

A saída da aplicação descreve cada ação concluída:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Utilizar identidade para monitorização e métricas

O ID do utilizador destina-se a funcionar como uma chave primária para registos e métricas que são recolhidas através do Azure Monitor. Para visualizar todas as chamadas de um utilizador, por exemplo, pode configurar a sua autenticação de forma a mapear uma identidade Azure Communication Services específica (ou identidades) para um único utilizador.

Saiba mais sobre conceitos de autenticação, ligue para diagnósticos através de análise de registos e métricas que estejam disponíveis para si.

Limpar os recursos

Para limpar e remover uma assinatura de Serviços de Comunicação, elimine o grupo de recursos ou recursos. A eliminação de um grupo de recursos também elimina quaisquer outros recursos que lhe estejam associados. Para mais informações, consulte a secção "Limpar recursos" da Criar e gerir os recursos dos Serviços de Comunicação.

Passos seguintes

Neste início rápido, aprendeu a:

  • Gerir identidades
  • Emitir fichas de acesso
  • Utilizar a Identidade dos Serviços de Comunicação SDK

Também pode querer: