Bibliothèque cliente Azure Communication Common pour JavaScript - version 2.4.0

Ce package contient du code commun pour les bibliothèques Azure Communication Service.

Mise en route

Conditions préalables

• Un abonnement Azure.
• Ressource Communication Services existante. Si vous devez créer la ressource, vous pouvez utiliser le portail Azure , le Azure PowerShellou leAzure CLI .
• Avoir installé le @azure/identity paquet.

Installation en cours

npm install @azure/communication-common

npm install @azure/identity

Support des navigateurs

JavaScript groupé

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

Concepts clés

CommunicationTokenCredential et AzureCommunicationTokenCredential

Il s’agit CommunicationTokenCredential d’une interface utilisée pour authentifier un utilisateur auprès des services de communication, tels que le chat ou l’appel.

Il AzureCommunicationTokenCredential offre un moyen pratique de créer des informations d’identification implémentant ladite interface et vous permet de tirer parti de la logique d’actualisation automatique intégrée.

Selon votre scénario, vous pouvez initialiser le AzureCommunicationTokenCredential avec :

• un jeton statique (adapté aux clients de courte durée utilisés par exemple pour envoyer des messages de chat uniques) ou
• une fonction de rappel qui assure un état d’authentification continu pendant les communications (idéal par exemple pour les longues sessions d’appel).
• des informations d’identification de jeton capables d’obtenir un jeton d’utilisateur Entra. Vous pouvez fournir n’importe quelle implémentation de l’interface TokenCredential. Il convient aux scénarios où des jetons d’accès utilisateur Entra sont nécessaires pour s’authentifier auprès de Communication Services.

Les jetons fournis à l’aide du AzureCommunicationTokenCredential constructeur ou du rappel de rafraîchissement de jeton peuvent être obtenus à l’aide de la bibliothèque Azure Communication Identity.

Exemples

Créer des informations d’identification avec un jeton statique

Pour les clients de courte durée, il n’est pas nécessaire d’actualiser le jeton à l’expiration et il peut être instancié à l’aide d’un AzureCommunicationTokenCredential jeton statique.

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

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

Créer des informations d’identification avec un rappel

Ici, nous supposons que nous avons une fonction fetchTokenFromMyServerForUser qui effectue une requête réseau pour récupérer une chaîne de jeton JWT pour un utilisateur. Nous le transmettons dans l’identifiant pour récupérer un jeton pour Bob à partir de notre propre serveur. Notre serveur utiliserait la bibliothèque Azure Communication Identity pour émettre des jetons. Il est nécessaire que la fetchTokenFromMyServerForUser fonction renvoie un jeton valide (avec une date d’expiration définie dans le futur) à tout moment.

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

Créer des informations d’identification avec l’actualisation proactive

La définition refreshProactively de true appellera votre tokenRefresher fonction lorsque le jeton est proche de l’expiration.

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

Créer des informations d’identification avec une actualisation proactive et un jeton initial

Le passage initialToken est une optimisation facultative permettant d’ignorer le premier appel à tokenRefresher. Vous pouvez l’utiliser pour séparer le démarrage de votre application des cycles d’actualisation de jeton suivants.

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

Créez des informations d’identification avec des informations d’identification de jeton capables d’obtenir un jeton d’utilisateur Entra

Pour les scénarios où un utilisateur Entra peut être utilisé avec Communication Services, vous devez initialiser n’importe quelle implémentation de l’interface TokenCredential et la fournir à l' EntraCommunicationTokenCredentialOptions. Parallèlement à cela, vous devez fournir l’URI de la ressource Azure Communication Services et les étendues requises pour le jeton d’utilisateur Entra. Ces étendues déterminent les autorisations accordées au jeton.

Cette approche doit être utilisée pour autoriser un utilisateur Entra disposant d’une licence Teams à utiliser les fonctionnalités d’extensibilité du téléphone Teams via votre ressource Azure Communication Services. Cela nécessite de fournir la https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls portée.

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

Les autres scénarios d’utilisation d’Azure Communication Services par les utilisateurs d’Entra sont actuellement en préversion uniquement et ne doivent pas être utilisés en production. Les étendues de ces scénarios suivent le format https://communication.azure.com/clients/<ACS Scope>. Si aucune portée spécifique n’est fournie, les portées par défaut seront définies sur 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);

Résolution des problèmes

• Jeton non valide spécifié : assurez-vous que le jeton que vous transmettez au constructeur ou au AzureCommunicationTokenCredentialtokenRefresher rappel est une chaîne de jeton JWT nue. Par exemple, si vous utilisez la bibliothèque Azure Communication Identity ou l’API REST pour obtenir le jeton, assurez-vous de ne transmettre que la token partie de l’objet de réponse.

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Étapes suivantes

• En savoir plus sur les jetons d’accès utilisateur de communication

Contribuer

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Projets connexes

• Kit de développement logiciel (SDK) Microsoft Azure pour JavaScript