Freigeben über

Allgemeine Azure-Kommunikationsclientbibliothek für JavaScript – Version 2.4.0

Dieses Paket enthält allgemeinen Code für Azure Communication Service-Bibliotheken.

Erste Schritte

Voraussetzungen

Installieren

npm install @azure/communication-common

npm install @azure/identity

Browserunterstützung

JavaScript-Bundle

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

Wichtige Begriffe

CommunicationTokenCredential und AzureCommunicationTokenCredential

Dabei CommunicationTokenCredential handelt es sich um eine Schnittstelle, die zum Authentifizieren eines Benutzers bei Kommunikationsdiensten wie Chat oder Anrufen verwendet wird.

Das AzureCommunicationTokenCredential bietet eine bequeme Möglichkeit, eine Anmeldeinformation zu erstellen, die die besagte Schnittstelle implementiert, und ermöglicht es Ihnen, die integrierte Auto-Refresh-Logik zu nutzen.

Abhängig von Ihrem Szenario können Sie die AzureCommunicationTokenCredential initialisieren mit:

  • ein statisches Token (geeignet für kurzlebige Clients, die z.B. zum Versenden von einmaligen Chat-Nachrichten verwendet werden) oder
  • eine Callback-Funktion, die einen kontinuierlichen Authentifizierungsstatus während der Kommunikation gewährleistet (ideal z.B. für lange Calling-Sitzungen).
  • einen Token-Berechtigungsnachweis, der in der Lage ist, ein Entra Benutzer-Token zu erhalten. Sie können eine beliebige Implementierung der TokenCredential-Schnittstelle bereitstellen. Es eignet sich für Szenarien, in denen Entra Benutzerzugriffstoken für die Authentifizierung bei Communication Services benötigt werden.

Die Token, die AzureCommunicationTokenCredential entweder über den Konstruktor oder über den Tokenaktualisierungsrückruf bereitgestellt werden, können mithilfe der Azure Communication Identity-Bibliothek abgerufen werden.

Beispiele

Erstellen von Anmeldeinformationen mit einem statischen Token

Bei kurzlebigen Clients ist es nicht erforderlich, das Token nach Ablauf zu aktualisieren, und es AzureCommunicationTokenCredential kann mit einem statischen Token instanziiert werden.

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

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

Erstellen von Anmeldeinformationen mit einem Rückruf

Hier gehen wir davon aus, dass wir eine Funktion fetchTokenFromMyServerForUser haben, die eine Netzwerkanforderung zum Abrufen eines JWT-Token-Strings für einen Benutzer stellt. Wir übergeben es in die Anmeldeinformationen, um ein Token für Bob von unserem eigenen Server abzurufen. Unser Server verwendet die Azure Communication Identity-Bibliothek zum Ausstellen von Token. Es ist notwendig, dass die fetchTokenFromMyServerForUser Funktion jederzeit ein gültiges Token (mit einem in der Zukunft festgelegten Ablaufdatum) zurückgibt.

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

Erstellen von Anmeldeinformationen mit proaktiver Aktualisierung

Wenn Sie auf true festlegen refreshProactively , wird Ihre tokenRefresher Funktion aufgerufen, wenn das Token kurz vor dem Ablauf steht.

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

Erstellen von Anmeldeinformationen mit proaktiver Aktualisierung und einem anfänglichen Token

Das Übergeben initialToken ist eine optionale Optimierung, um den ersten Aufruf von tokenRefresherzu überspringen. Sie können dies verwenden, um den Start von Ihrer Anwendung von nachfolgenden Tokenaktualisierungszyklen zu trennen.

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

Erstellen Sie Anmeldeinformationen mit Token-Anmeldeinformationen, die in der Lage sind, ein Entra Benutzertoken abzurufen

In Szenarien, in denen ein Entra Benutzer mit Communication Services verwendet werden kann, müssen Sie eine Implementierung der TokenCredential-Schnittstelle initialisieren und für .EntraCommunicationTokenCredentialOptions Darüber hinaus müssen Sie den URI der Azure Communication Services-Ressource und die für das Antera-Benutzertoken erforderlichen Bereiche angeben. Diese Bereiche bestimmen die Berechtigungen, die dem Token erteilt werden.

Dieser Ansatz muss verwendet werden, um einen Entra Benutzer mit einer Teams-Lizenz zu autorisieren, Teams Phone Extensibility-Funktionen über Ihre Azure Communication Services-Ressource zu verwenden. Dies erfordert die Bereitstellung des Umfangs 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);

Andere Szenarien für die Nutzung von Azure Communication Services durch Entra-Benutzer befinden sich derzeit nur in der Vorschauphase und sollten nicht in der Produktion verwendet werden. Die Bereiche für diese Szenarien folgen dem Format https://communication.azure.com/clients/<ACS Scope>. Wenn bestimmte Bereiche nicht angegeben werden, werden die Standardbereiche auf https://communication.azure.com/clients/.defaultfestgelegt.

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

Problembehandlung

  • Ungültiges Token angegeben: Stellen Sie sicher, dass das Token, das Sie an den AzureCommunicationTokenCredential Konstruktor oder den tokenRefresher Callback übergeben, eine bloße JWT-Tokenzeichenfolge ist. Wenn Sie z. B. die Azure Communication Identity-Bibliothek oder die REST-API zum Abrufen des Tokens verwenden, stellen Sie sicher, dass Sie nur den token Teil des Antwortobjekts übergeben.

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Nächste Schritte

Mitarbeit

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.