Compartir a través de

Biblioteca cliente común de Azure Communication para JavaScript: versión 2.4.0

Este paquete contiene código común para las bibliotecas de Azure Communication Service.

Cómo empezar

Prerrequisitos

Instalar

npm install @azure/communication-common

npm install @azure/identity

Compatibilidad con navegadores

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para obtener más información sobre cómo hacerlo, consulte nuestra documentación de agrupación de .

Conceptos clave

CommunicationTokenCredential y AzureCommunicationTokenCredential

Es CommunicationTokenCredential una interfaz que se utiliza para autenticar a un usuario con servicios de comunicación, como chat o llamadas.

Ofrece AzureCommunicationTokenCredential una forma conveniente de crear una credencial implementando dicha interfaz y le permite aprovechar la lógica de actualización automática incorporada.

En función de su escenario, es posible que desee inicializar el AzureCommunicationTokenCredential archivo con:

  • un token estático (adecuado para clientes de corta duración utilizados, por ejemplo, para enviar mensajes de chat únicos) o
  • una función de devolución de llamada que garantiza un estado de autenticación continuo durante las comunicaciones (ideal, por ejemplo, para sesiones de llamadas largas).
  • una credencial de token capaz de obtener un token de usuario de Entra. Puede proporcionar cualquier implementación de la interfaz TokenCredential. Es adecuado para escenarios en los que se necesitan tokens de acceso de usuario de Entra para autenticarse con Communication Services.

Los tokens proporcionados a través AzureCommunicationTokenCredential del constructor o a través de la devolución de llamada del actualizador de tokens se pueden obtener mediante la biblioteca de Azure Communication Identity.

Ejemplos

Creación de una credencial con un token estático

Para los clientes de corta duración, no es necesario actualizar el token al vencimiento y AzureCommunicationTokenCredential se puede crear una instancia con un token estático.

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

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

Creación de una credencial con una devolución de llamada

Aquí suponemos que tenemos una función fetchTokenFromMyServerForUser que realiza una solicitud de red para recuperar una cadena de token JWT para un usuario. Lo pasamos a la credencial para obtener un token para Bob desde nuestro propio servidor. Nuestro servidor usaría la biblioteca de identidad de comunicación de Azure para emitir tokens. Es necesario que la fetchTokenFromMyServerForUser función devuelva un token válido (con una fecha de caducidad establecida en el futuro) en todo momento.

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

Creación de una credencial con actualización proactiva

Si se establece refreshProactively en true, se llamará a la tokenRefresher función cuando el token esté a punto de caducar.

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

Creación de una credencial con actualización proactiva y un token inicial

Pasar initialToken es una optimización opcional para omitir la primera llamada a tokenRefresher. Puede usar esto para separar el arranque de la aplicación de los ciclos de actualización de tokens posteriores.

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

Cree una credencial con una credencial de token capaz de obtener un token de usuario de Entra

En escenarios en los que se puede usar un usuario de Entra con Communication Services, debe inicializar cualquier implementación de la interfaz TokenCredential y proporcionarla EntraCommunicationTokenCredentialOptionsal archivo . Junto con esto, debe proporcionar el URI del recurso de Azure Communication Services y los ámbitos necesarios para el token de usuario de Entra. Estos ámbitos determinan los permisos concedidos al token.

Este enfoque debe usarse para autorizar a un usuario de Entra con una licencia de Teams a usar las características de extensibilidad del teléfono de Teams a través del recurso de Azure Communication Services. Para ello, es necesario proporcionar el https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls alcance.

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

Otros escenarios para que los usuarios de Entra usen Azure Communication Services solo se encuentran actualmente en la fase de versión preliminar y no se deben usar en producción. Los ámbitos de estos escenarios siguen el formato https://communication.azure.com/clients/<ACS Scope>. Si no se proporcionan ámbitos específicos, los ámbitos predeterminados se establecerán en 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);

Solución de problemas

  • Token no válido especificado: asegúrese de que el token que está pasando al AzureCommunicationTokenCredential constructor o a la devolución de tokenRefresher llamada es una cadena de token JWT desnuda. Por ejemplo, si usa la biblioteca de Azure Communication Identity o la API de REST para obtener el token, asegúrese de pasar solo la token parte del objeto de respuesta.

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

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

setLogLevel("info");

Pasos siguientes

Contribución

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.