Delen via

Azure Communication Gemeenschappelijke clientbibliotheek voor JavaScript - versie 2.4.0

Dit pakket bevat algemene code voor Azure Communication Service-bibliotheken.

Aan de slag

Vereiste voorwaarden

Installeren

npm install @azure/communication-common

npm install @azure/identity

Browserondersteuning

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.

Belangrijke concepten

CommunicationTokenCredential en AzureCommunicationTokenCredential

Het CommunicationTokenCredential is een interface die wordt gebruikt om een gebruiker te verifiëren met Communicatiediensten, zoals Chat of Bellen.

Het AzureCommunicationTokenCredential biedt een handige manier om een referentie te maken die de genoemde interface implementeert en stelt u in staat om te profiteren van de ingebouwde logica voor automatisch vernieuwen.

Afhankelijk van uw scenario kunt u de AzureCommunicationTokenCredential volgende initialiseren:

  • een static token (geschikt voor kortstondige clients die bijvoorbeeld eenmalige chatberichten versturen) of
  • een terugbelfunctie die zorgt voor een continue authenticatiestatus tijdens communicatie (ideaal bijvoorbeeld voor lange belsessies).
  • een tokenreferentie waarmee een Entra-gebruikerstoken kan worden verkregen. U kunt elke implementatie van de TokenCredential-interface bieden. Het is geschikt voor scenario's waarin Entra-gebruikerstoegangstokens nodig zijn om te verifiëren met communicatieservices.

De tokens die via de constructor of via de aanroep van de tokenvernieuwing worden AzureCommunicationTokenCredential geleverd, kunnen worden verkregen met behulp van de Azure Communication Identity-bibliotheek.

Voorbeelden

Een referentie maken met een statisch token

Voor klanten met een korte levensduur is het niet nodig om het token na afloop te vernieuwen en kan het AzureCommunicationTokenCredential worden geïnstantieerd met een statisch token.

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

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

Een referentie maken met een callback

Hier gaan we ervan uit dat we een functie fetchTokenFromMyServerForUser hebben die een netwerkverzoek doet om een JWT-tokenstring voor een gebruiker op te halen. We geven het door aan de inloggegevens om een token voor Bob op te halen van onze eigen server. Onze server gebruikt de Azure Communication Identity-bibliotheek om tokens uit te geven. Het is noodzakelijk dat de fetchTokenFromMyServerForUser functie te allen tijde een geldig token retourneert (met een vervaldatum die in de toekomst is ingesteld).

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

Maak een referentie met proactief vernieuwen

Als u deze instelt refreshProactively op true, wordt uw tokenRefresher functie aangeroepen wanneer het token bijna verloopt.

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

Maak een referentie met proactief vernieuwen en een eerste token

Passen initialToken is een optionele optimalisatie om de eerste oproep naar tokenRefresher. U kunt dit gebruiken om het opstarten van uw toepassing te scheiden van de volgende vernieuwingscycli van tokens.

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

Maak een referentie met een tokenreferentie waarmee een Entra-gebruikerstoken kan worden verkregen

Voor scenario's waarin een Entra-gebruiker kan worden gebruikt met communicatieservices, moet u elke implementatie van de TokenCredential-interface initialiseren en deze verstrekken aan de EntraCommunicationTokenCredentialOptions. Daarnaast moet u de URI van de Azure Communication Services-resource en de bereiken opgeven die nodig zijn voor het Entra-gebruikerstoken. Deze bereiken bepalen de machtigingen die aan het token worden verleend.

Deze benadering moet worden gebruikt voor het autoriseren van een Entra-gebruiker met een Teams-licentie voor het gebruik van Teams Phone Extensibility-functies via uw Azure Communication Services-resource. Dit vereist het verstrekken van de https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls scope.

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 scenario's voor Entra-gebruikers om Azure Communication Services te gebruiken, bevinden zich momenteel alleen in de preview-fase en mogen niet in productie worden gebruikt. De scopes voor deze scenario's volgen de indeling https://communication.azure.com/clients/<ACS Scope>. Als er geen specifieke bereiken zijn opgegeven, worden de standaardbereiken ingesteld op 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);

Probleemoplossingsproces

  • Ongeldig token opgegeven: zorg ervoor dat het token dat u doorgeeft aan de AzureCommunicationTokenCredential constructor of aan de tokenRefresher callback een kale JWT-tokentekenreeks is. Als u bijvoorbeeld de Azure Communication Identity-bibliotheek of REST API gebruikt om het token te verkrijgen, moet u ervoor zorgen dat u slechts een deel van het token antwoordobject doorgeeft.

Loggen

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Volgende stappen

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

  • Last updated on