Biblioteca de cliente do Azure Communication Common 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 de Serviços de Comunicação existente. Se precisar criar o recurso, você pode usar o do Portal doAzure, o doAzure PowerShell ou o da CLI doAzure.
• Ter o @azure/identity pacote instalado.

Instalação

npm install @azure/communication-common

npm install @azure/identity

Suporte de navegador

Pacote JavaScript

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

Conceitos-chave

CommunicationTokenCredential e AzureCommunicationTokenCredential

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

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 cenário, convém inicializar o AzureCommunicationTokenCredential com:

• um token estático (adequado para clientes de curta duração usado 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ínua 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 Entra. Você pode fornecer qualquer implementação da interface TokenCredential. É 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 construtor ou por meio do retorno de chamada de atualização de token podem ser obtidos usando a biblioteca de Identidade de Comunicação do Azure.

Exemplos

Criar uma credencial com um token estático

Para clientes de curta duração, atualizar o token após a expiração não é necessário e o pode ser instanciado AzureCommunicationTokenCredential 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 que faz uma solicitação fetchTokenFromMyServerForUser de rede para recuperar uma cadeia de caracteres 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"),
});

Crie uma credencial com atualização proativa

A configuração refreshProactively como true chamará sua tokenRefresher função quando o token estiver perto de expirar.

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

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

A aprovação initialToken é uma otimização opcional para pular 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",
});

Crie uma credencial com uma credencial de token capaz de obter um token de usuário 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 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 do Telefone do Teams por meio do recurso dos Serviços de Comunicação do Azure. Para tal, é necessário prever o âmbito de https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls aplicação.

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

Solução de problemas

• Token inválido especificado: certifique-se de que 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.

Exploração Florestal

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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

• Ler mais acerca de Tokens de acesso de utilizador de comunicações

Contribuir

Se você quiser contribuir para esta 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