Libreria client comune di Azure Communication per JavaScript - versione 2.4.0

Questo pacchetto contiene codice comune per le librerie del servizio di comunicazione di Azure.

Come iniziare

Prerequisiti

Una sottoscrizione di Azure.
Una risorsa di Servizi di comunicazione esistente. Se è necessario creare la risorsa, è possibile usare il portale di Azure , il Azure PowerShello l'interfaccia della riga di comando di Azure .
Avere il @azure/identity pacchetto installato.

Installazione in corso

npm install @azure/communication-common

npm install @azure/identity

Supporto del browser

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

Concetti chiave

CommunicationTokenCredential e AzureCommunicationTokenCredential

Si CommunicationTokenCredential tratta di un'interfaccia utilizzata per autenticare un utente con Servizi di comunicazione, ad esempio Chat o Chiamate.

Offre AzureCommunicationTokenCredential un modo conveniente per creare una credenziale implementando la suddetta interfaccia e consente di sfruttare la logica di aggiornamento automatico integrata.

A seconda dello scenario, è possibile inizializzare con AzureCommunicationTokenCredential :

un token statico (adatto per client di breve durata utilizzati, ad esempio, per inviare messaggi di chat una tantum) o
una funzione di callback che garantisce uno stato di autenticazione continuo durante le comunicazioni (ideale ad esempio per lunghe sessioni di chiamata).
una credenziale di token in grado di ottenere un token utente Entra. È possibile fornire qualsiasi implementazione dell'interfaccia TokenCredential. È adatto per gli scenari in cui sono necessari i token di accesso utente Entra per l'autenticazione con Servizi di comunicazione.

I token forniti al AzureCommunicationTokenCredential tramite il costruttore o tramite il callback di aggiornamento dei token possono essere ottenuti usando la libreria Azure Communication Identity.

Esempi

Creare una credenziale con un token statico

Per i client di breve durata, l'aggiornamento del token alla scadenza non è necessario e può essere creata un'istanza AzureCommunicationTokenCredential con un token statico.

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

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

Creare una credenziale con una richiamata

Qui supponiamo di avere una funzione fetchTokenFromMyServerForUser che effettua una richiesta di rete per recuperare una stringa di token JWT per un utente. Lo passiamo nelle credenziali per recuperare un token per Bob dal nostro server. Il server userebbe la libreria Azure Communication Identity per emettere token. È necessario che la fetchTokenFromMyServerForUser funzione restituisca sempre un token valido (con una data di scadenza impostata in futuro).

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

Creare una credenziale con l'aggiornamento proattivo

L'impostazione refreshProactively su true chiamerà la tokenRefresher funzione quando il token è prossimo alla scadenza.

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

Creare una credenziale con aggiornamento proattivo e un token iniziale

Il passaggio initialToken è un'ottimizzazione facoltativa per ignorare la prima chiamata a tokenRefresher. È possibile utilizzare questa opzione per separare l'avvio dall'applicazione dai cicli di aggiornamento dei token successivi.

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

Creare una credenziale con una credenziale token in grado di ottenere un token utente Entra

Per gli scenari in cui un utente Entra può essere utilizzato con Servizi di comunicazione, è necessario inizializzare qualsiasi implementazione dell'interfaccia TokenCredential e fornirla a EntraCommunicationTokenCredentialOptions. Oltre a ciò, è necessario fornire l'URI della risorsa Servizi di comunicazione di Azure e gli ambiti necessari per il token utente Entra. Questi ambiti determinano le autorizzazioni concesse al token.

Questo approccio deve essere usato per autorizzare un utente Entra con una licenza di Teams a usare le funzionalità di estendibilità telefonica di Teams tramite la risorsa di Servizi di comunicazione di Azure. Ciò richiede di fornire l'ambito https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls .

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

Altri scenari per gli utenti Entra per l'uso di Servizi di comunicazione di Azure sono attualmente solo nella fase di anteprima e non devono essere usati nell'ambiente di produzione. Gli ambiti per questi scenari seguono il formato https://communication.azure.com/clients/<ACS Scope>. Se non vengono forniti ambiti specifici, gli ambiti predefiniti verranno impostati su 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);

Risoluzione dei problemi

Token specificato non valido: assicurarsi che il token che si sta passando al AzureCommunicationTokenCredential costruttore o al tokenRefresher callback sia una stringa di token JWT semplice. Ad esempio, se si usa la libreria Azure Communication Identity o l'API REST per ottenere il token, assicurarsi di passare solo la token parte dell'oggetto risposta.

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Passaggi successivi

Scopri di più sui token di accesso utente per le comunicazioni

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

Microsoft Azure SDK per Javascript

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-06-06