Sdílet prostřednictvím

Společná klientská knihovna Azure Communication pro JavaScript – verze 2.4.0

Tento balíček obsahuje společný kód pro knihovny služby Azure Communication Service.

Začínáme

Požadavky

  • Předplatné služby Azure.
  • Existující prostředek komunikační služby. Pokud potřebujete prostředek vytvořit, můžete použít webuAzure Portal, Azure PowerShellu nebo Azure CLI.
  • S nainstalovaným @azure/identity balíčkem.

Instalování

npm install @azure/communication-common

npm install @azure/identity

Podpora prohlížečů

JavaScriptový balíček

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci sdružování.

Klíčové koncepty

CommunicationTokenCredential a AzureCommunicationTokenCredential

Jedná CommunicationTokenCredential se o rozhraní používané k ověření uživatele pomocí komunikačních služeb, jako je chat nebo volání.

Nabízí AzureCommunicationTokenCredential pohodlný způsob, jak vytvořit přihlašovací údaje implementující uvedené rozhraní a umožňuje vám využít výhod vestavěné logiky automatického obnovení.

V závislosti na vašem scénáři můžete chtít inicializovat AzureCommunicationTokenCredential pomocí:

  • statický token (vhodný pro krátkodobé klienty sloužící např. k odesílání jednorázových Chat zpráv) nebo
  • funkce zpětného volání, která zajišťuje nepřetržitý stav autentizace během komunikace (ideální např. pro dlouhé relace volání).
  • přihlašovací údaje tokenu schopné získat uživatelský token Entra. Můžete poskytnout libovolnou implementaci rozhraní TokenCredential. Je vhodný pro scénáře, kdy jsou k ověření pomocí komunikačních služeb potřeba přístupové tokeny uživatelů Entra.

Tokeny dodané buď AzureCommunicationTokenCredential prostřednictvím konstruktoru, nebo prostřednictvím zpětného volání obnovovače tokenu lze získat pomocí knihovny Azure Communication Identity.

Příklady

Vytvoření přihlašovacích údajů se statickým tokenem

U klientů s krátkou životností není aktualizace tokenu po vypršení platnosti nutná a může být vytvořena AzureCommunicationTokenCredential instance se statickým tokenem.

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

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

Vytvoření přihlašovacích údajů se zpětným voláním

Zde předpokládáme, že máme funkci fetchTokenFromMyServerForUser , která vytvoří síťový požadavek na načtení řetězce tokenu JWT pro uživatele. Předáme ho do přihlašovacích údajů, abychom získali token pro Boba z našeho vlastního serveru. Náš server by k vydávání tokenů používal knihovnu Azure Communication Identity. Je nutné, aby fetchTokenFromMyServerForUser funkce vždy vracela platný token (s datem vypršení platnosti nastaveným v budoucnosti).

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

Vytvoření přihlašovacích údajů s proaktivní aktualizací

Nastavení refreshProactively na true zavolá vaši tokenRefresher funkci, když se blíží vypršení platnosti tokenu.

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

Vytvoření přihlašovacích údajů s proaktivní aktualizací a počátečním tokenem

Předávání initialToken je volitelná optimalizace pro přeskočení prvního volání rozhraní tokenRefresher. To můžete použít k oddělení spouštění od aplikace od následných cyklů aktualizace tokenu.

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

Vytvoření přihlašovacích údajů s pověření tokenu schopným získat token uživatele Entra

Ve scénářích, kdy lze uživatele Entra použít s komunikačními službami, je nutné inicializovat jakoukoli implementaci rozhraní TokenCredential a poskytnout ji rozhraní EntraCommunicationTokenCredentialOptions. Spolu s tím musíte zadat identifikátor URI prostředku Azure Communication Services a rozsahy požadované pro token uživatele Entra. Tyto obory určují oprávnění udělená tokenu.

Tento přístup je potřeba použít k autorizaci uživatele Entra s licencí Teams k používání funkcí rozšiřitelnosti telefonu Teams prostřednictvím vašeho prostředku Azure Communication Services. To vyžaduje poskytnutí https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls rozsahu.

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

Další scénáře, které mohou uživatelé Entry využívat Azure Communication Services, jsou v současné době pouze ve fázi náhledu a neměly by se používat v produkčním prostředí. Rozsahy pro tyto scénáře mají formát https://communication.azure.com/clients/<ACS Scope>. Pokud nejsou k dispozici konkrétní rozsahy, budou výchozí rozsahy nastaveny na 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);

Řešení problémů

  • Zadaný neplatný token: Ujistěte se, že token, který předáváte konstruktoru AzureCommunicationTokenCredential nebo zpětnému volání, tokenRefresher je holý řetězec tokenu JWT. Pokud například k získání tokenu používáte knihovnu Azure Communication Identity neborozhraní REST API , ujistěte se, že předáváte pouze část token objektu odpovědi.

Logování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Další kroky

Přispění

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

  • Last updated on