Biblioteca de clientes comum de comunicação do Azure para JavaScript – versão 2.4.0

Este pacote contém código comum para bibliotecas do Serviço de Comunicação do Azure.

Como começar

Pré-requisitos

• Uma assinatura do Azure.
• Um recurso existente dos Serviços de Comunicação. Se você precisar criar o recurso, poderá usar o Portal do Azure, o do Azure PowerShell ou a CLI do Azure .
• Ter o @azure/identity pacote instalado.

Instalar

npm install @azure/communication-common

npm install @azure/identity

Suporte ao navegador

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento .

Conceitos principais

CommunicationTokenCredential e AzureCommunicationTokenCredential

A CommunicationTokenCredential é uma interface usada para autenticar um usuário com os Serviços de Comunicação, como Chat ou Chamadas.

O AzureCommunicationTokenCredential oferece uma maneira conveniente de criar uma credencial implementando a referida interface e permite que você aproveite a lógica de atualização automática integrada.

Dependendo do seu cenário, talvez você queira inicializar o AzureCommunicationTokenCredential com:

• um token estático (adequado para clientes de curta duração usados para, por exemplo, enviar mensagens de bate-papo únicas) ou
• uma função de retorno de chamada que garante um estado de autenticação contínuo durante as comunicações (ideal, por exemplo, para longas sessões de chamada).
• uma credencial de token capaz de obter um token de usuário do Entra. Você pode fornecer qualquer implementação da interface TokenCredential. Ele é adequado para cenários em que os tokens de acesso de usuário do Entra são necessários para autenticar com os Serviços de Comunicação.

Os tokens fornecidos ao AzureCommunicationTokenCredential por meio do construtor ou por meio do retorno de chamada do atualizador de token podem ser obtidos usando a biblioteca do Azure Communication Identity.

Exemplos

Criar uma credencial com um token estático

Para clientes de curta duração, não é necessário atualizar o token após a expiração e pode AzureCommunicationTokenCredential ser instanciado com um token estático.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

const tokenCredential = new AzureCommunicationTokenCredential(
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
);

Criar uma credencial com um retorno de chamada

Aqui, assumimos que temos uma função fetchTokenFromMyServerForUser que faz uma solicitação de rede para recuperar uma string de token JWT para um usuário. Nós o passamos para a credencial para buscar um token para Bob em nosso próprio servidor. Nosso servidor usaria a biblioteca de Identidade de Comunicação do Azure para emitir tokens. É necessário que a fetchTokenFromMyServerForUser função retorne um token válido (com uma data de expiração definida no futuro) em todos os momentos.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
});

Criar uma credencial com atualização proativa

A configuração refreshProactively como true chamará sua tokenRefresher função quando o token estiver próximo da expiração.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
  refreshProactively: true,
});

Criar uma credencial com atualização proativa e um token inicial

A passagem initialToken é uma otimização opcional para ignorar a primeira chamada para tokenRefresher. Você pode usar isso para separar a inicialização do seu aplicativo dos ciclos de atualização de token subsequentes.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
  refreshProactively: true,
  token:
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
});

Criar uma credencial com uma credencial de token capaz de obter um token de usuário do Entra

Para cenários em que um usuário do Entra pode ser usado com os Serviços de Comunicação, você precisa inicializar qualquer implementação da interface TokenCredential e fornecê-la ao EntraCommunicationTokenCredentialOptions. Junto com isso, você deve fornecer o URI do recurso dos Serviços de Comunicação do Azure e os escopos necessários para o token de usuário do Entra. Esses escopos determinam as permissões concedidas ao token.

Essa abordagem precisa ser usada para autorizar um usuário do Entra com uma licença do Teams a usar os recursos de Extensibilidade de Telefonia do Teams por meio do recurso dos Serviços de Comunicação do Azure. Isso requer fornecer o https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls escopo.

import { InteractiveBrowserCredential } from "@azure/identity";
import {
  EntraCommunicationTokenCredentialOptions,
  AzureCommunicationTokenCredential,
} from "@azure/communication-common";

const options = {
  tenantId: "<your-tenant-id>",
  clientId: "<your-client-id>",
  redirectUri: "<your-redirect-uri>",
};
const entraTokenCredential = new InteractiveBrowserCredential(options);

const entraTokenCredentialOptions: EntraCommunicationTokenCredentialOptions = {
  resourceEndpoint: "https://<your-resource>.communication.azure.com",
  tokenCredential: entraTokenCredential,
  scopes: ["https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls"],
};

const credential = new AzureCommunicationTokenCredential(entraTokenCredentialOptions);

Outros cenários para os usuários do Entra utilizarem os Serviços de Comunicação do Azure estão atualmente apenas no estágio de visualização e não devem ser usados na produção. Os escopos para esses cenários seguem o formato https://communication.azure.com/clients/<ACS Scope>. Se escopos específicos não forem fornecidos, os escopos padrão serão definidos como https://communication.azure.com/clients/.default.

import { InteractiveBrowserCredential } from "@azure/identity";
import {
  EntraCommunicationTokenCredentialOptions,
  AzureCommunicationTokenCredential,
} from "@azure/communication-common";

const options = {
  tenantId: "<your-tenant-id>",
  clientId: "<your-client-id>",
  redirectUri: "<your-redirect-uri>",
};
const entraTokenCredential = new InteractiveBrowserCredential(options);

const entraTokenCredentialOptions: EntraCommunicationTokenCredentialOptions = {
  resourceEndpoint: "https://<your-resource>.communication.azure.com",
  tokenCredential: entraTokenCredential,
  scopes: ["https://communication.azure.com/clients/VoIP"],
};

const credential = new AzureCommunicationTokenCredential(entraTokenCredentialOptions);

Resolução de problemas

• Token inválido especificado: verifique se o token que você está passando para o AzureCommunicationTokenCredential construtor ou para o retorno de tokenRefresher chamada é uma cadeia de caracteres de token JWT simples. Por exemplo, se você estiver usando a biblioteca de Identidade de Comunicação do Azure ou a API REST para obter o token, verifique se está passando apenas a token parte do objeto de resposta.

Registro

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Próximas etapas

• Leia mais sobre Tokens de acesso do usuário de comunicação

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Projetos relacionados

• SDK do Microsoft Azure para Javascript