Azure Communication Common client library for JavaScript - verzió 2.5.0

Ez a csomag közös kódot tartalmaz az Azure Communication Service kódtárakhoz.

Kezdő lépések

Előfeltételek

Telepítése

npm install @azure/communication-common

npm install @azure/identity

Böngésző támogatás

JavaScript-csomag

Ahhoz, hogy ezt az ügyfélkódtárat a böngészőben használhassa, először egy kötegelőt kell használnia. Ennek módjáról további információt a csomagküldő dokumentációbantalál.

Főbb fogalmak

CommunicationTokenCredential és AzureCommunicationTokenCredential

Ez CommunicationTokenCredential egy olyan felület, amely a felhasználó hitelesítésére szolgál a kommunikációs szolgáltatásokkal, például a csevegéssel vagy a hívással.

Ez AzureCommunicationTokenCredential kényelmes módot kínál az említett felületet megvalósító hitelesítő adatok létrehozására, és lehetővé teszi a beépített automatikus frissítési logika előnyeinek kihasználását.

A forgatókönyvtől függően érdemes lehet inicializálni a AzureCommunicationTokenCredential következővel:

  • statikus token (alkalmas rövid életű kliensek számára, pl. egyszeri csevegőüzenetek küldésére) vagy
  • visszahívási funkció, amely folyamatos hitelesítési állapotot biztosít a kommunikáció során (ideális pl. hosszú hívási munkamenetekhez).
  • egy Entra felhasználói jogkivonat beszerzésére alkalmas jogkivonat. A TokenCredential felület bármilyen implementációját biztosíthatja. Olyan forgatókönyvekhez alkalmas, ahol Entra felhasználói hozzáférési jogkivonatokra van szükség a Communication Services hitelesítéshez.

A konstruktoron vagy a jogkivonat-frissítő visszahívásán keresztül megadott AzureCommunicationTokenCredential jogkivonatok a Azure Communication Identity kódtár használatával szerezhetők be.

Példák

Hitelesítő adatok létrehozása statikus jogkivonattal

Rövid élettartamú ügyfelek esetén a jogkivonat lejáratkor történő frissítése nem szükséges, és statikus AzureCommunicationTokenCredential jogkivonattal példányosítható.

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

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

Hitelesítő adatok létrehozása visszahívással

Itt feltételezzük, hogy van egy függvényünk fetchTokenFromMyServerForUser , amely hálózati kérést küld egy JWT-jogkivonat karakterlánc lekérésére egy felhasználó számára. Átadjuk a hitelesítő adatoknak, hogy lekérjünk egy tokent Bob számára a saját szerverünkről. A kiszolgáló az Azure Communication Identity kódtárat használja a jogkivonatok kiadásához. A fetchTokenFromMyServerForUser függvénynek mindig érvényes jogkivonatot kell visszaadnia (a jövőben beállított lejárati dátummal).

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

Hitelesítő adatok létrehozása proaktív frissítéssel

Az igaz beállítás refreshProactively akkor hívja meg a függvényt tokenRefresher , amikor a jogkivonat közel van a lejárathoz.

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

Hitelesítő adatok létrehozása proaktív frissítéssel és kezdeti jogkivonattal

Az átadás initialToken egy opcionális optimalizálás az első hívás tokenRefresherkihagyásához. Ezzel elválaszthatja a rendszerindítást az alkalmazástól a későbbi jogkivonat-frissítési ciklusoktól.

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

Hozz létre egy titkosított vagy átláthatatlan hozzáférési tokenhez

Néhány hozzáférési tokenek – például az Entra vállalati felhasználók számára kiadott tokenek – titkosítottak, és nem lehet dekódolni az ügyfélen, így a jogosultság nem tudja olvasni a lejáratukat. A javasolt megközelítés, hogy visszaadsz egy AccessToken () -t a tokenválaszból tokenRefresherexpires_in(vagy passzolsz egy kezdeti token) beállítást expiresOnTimestamp .{ token, expiresOnTimestamp } Ez pontos a proaktív frissítési ütemezést.

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

// Some access tokens (e.g. for enterprise Entra users) are encrypted and cannot be
// decoded on the client. Return an AccessToken with an explicit expiry so proactive
// refresh scheduling stays accurate; derive expiresOnTimestamp from the response's expires_in.
async function fetchEncryptedTokenForUser(user: string): Promise<{
  token: string;
  expiresOnTimestamp: number;
}> {
  const response = { token: "some-encrypted-token-for-" + user, expiresInSeconds: 8 * 60 * 60 };
  return {
    token: response.token,
    expiresOnTimestamp: Date.now() + response.expiresInSeconds * 1000,
  };
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchEncryptedTokenForUser("bob@contoso.com"),
  refreshProactively: true,
});

Ha csak a token stringet tudod megadni, a hitelesítés elfogadja azt, és tartalék élettartamot feltételez. Állítsd undecodableTokenExpiryIntervalInSeconds be a tokenjeid tényleges élettartamára, hogy ne frissüljenek gyakrabban a szükséges időben; alapértelmezés szerint 600 másodperc.

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

function fetchOpaqueTokenForUser(user: string): Promise<string> {
  // Your custom implementation returns an opaque token string that can't be decoded.
  return Promise.resolve("some-opaque-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchOpaqueTokenForUser("bob@contoso.com"),
  refreshProactively: true,
  // When the token can't be decoded and no explicit expiry is provided, assume this
  // lifetime (in seconds) instead of the 600s default — set it to your tokens' real lifetime.
  undecodableTokenExpiryIntervalInSeconds: 3600,
});

Hitelesítő adatok létrehozása egy Entra felhasználói jogkivonat beszerzésére alkalmas jogkivonat-hitelesítő adatokkal

Olyan forgatókönyvek esetén, amikor egy Entra-felhasználó használható a Communication Services, inicializálnia kell a TokenCredential felület bármely implementációját, és meg kell adnia a EntraCommunicationTokenCredentialOptions. Ezzel együtt meg kell adnia a Azure Communication Services erőforrás URI-ját és az Entra felhasználói jogkivonathoz szükséges hatóköröket. Ezek a hatókörök határozzák meg a jogkivonatnak megadott engedélyeket.

Ezt a megközelítést kell használni egy Teams-licenccel rendelkező Entra-felhasználó engedélyezéséhez a Teams telefonbővíthetőségi funkcióinak használatára a Azure Communication Services erőforráson keresztül. Ehhez meg kell adni a hatókört https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls . A GCCH felhőkörnyezethez használd https://auth.msft.communication.azure.us/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);

Az Entra-felhasználók számára az Azure Communication Services használatára vonatkozó egyéb forgatókönyvek jelenleg csak előzetes verziójú szakaszban vannak, és nem használhatók éles környezetben. Ezeknek a forgatókönyveknek a hatóköre a következő formátumot https://communication.azure.com/clients/<ACS Scope>követi: . Ha nincs megadva adott hatókör, az alapértelmezett hatókör a következőre https://communication.azure.com/clients/.defaultlesz állítva: .

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

Hibaelhárítás

  • Érvénytelen jogkivonat megadva: Győződjön meg arról, hogy a AzureCommunicationTokenCredential konstruktornak vagy a tokenRefresher visszahívásnak átadott jogkivonat csupasz JWT-jogkivonat-sztring. Ha például a Azure Communication Identity kódtárat vagy a REST API-t használja a jogkivonat beszerzéséhez, győződjön meg arról, hogy csak a válaszobjektum részét adja át token .

Fakitermelés

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a környezeti változót a AZURE_LOG_LEVEL következőre info: . Alternatívaként a naplózás futásidőben is engedélyezhető a setLogLevel hívásával a @azure/logger.

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

setLogLevel("info");

Következő lépések

Közreműködés

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót, amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

  • Last updated on