Udostępnij za pomocą

Wspólna biblioteka klienta usługi Azure Communication dla języka JavaScript — wersja 2.4.0

Ten pakiet zawiera wspólny kod dla bibliotek Azure Communication Service.

Wprowadzenie

Wymagania wstępne

Instalowanie

npm install @azure/communication-common

npm install @azure/identity

Obsługa przeglądarek

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć pakietu. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów .

Najważniejsze pojęcia

CommunicationTokenCredential i AzureCommunicationTokenCredential

Jest to CommunicationTokenCredential interfejs używany do uwierzytelniania użytkownika za pomocą usług komunikacyjnych, takich jak czat lub połączenia.

Oferuje AzureCommunicationTokenCredential wygodny sposób tworzenia poświadczeń implementujących wspomniany interfejs i pozwala skorzystać z wbudowanej logiki automatycznego odświeżania.

W zależności od scenariusza możesz zainicjować plik AzureCommunicationTokenCredential with:

  • token statyczny (odpowiedni dla krótkotrwałych klientów przyzwyczajonych np. do wysyłania jednorazowych wiadomości na czacie) lub
  • funkcja wywołania zwrotnego, która zapewnia ciągły stan uwierzytelniania podczas komunikacji (idealne np. w przypadku długich sesji telefonicznych).
  • poświadczenie tokenu umożliwiające uzyskanie tokenu użytkownika Entra. Możesz podać dowolną implementację interfejsu TokenCredential. Jest ona odpowiednia dla scenariuszy, w których tokeny dostępu użytkownika Entra są potrzebne do uwierzytelniania za pomocą usług komunikacyjnych.

Tokeny dostarczone do obiektu za AzureCommunicationTokenCredential pośrednictwem konstruktora lub za pośrednictwem wywołania zwrotnego odświeżania tokenu można uzyskać przy użyciu biblioteki tożsamości komunikacyjnej platformy Azure.

Przykłady

Tworzenie poświadczeń przy użyciu tokenu statycznego

W przypadku klientów krótkotrwałych odświeżanie tokenu po wygaśnięciu nie jest konieczne i można go AzureCommunicationTokenCredential utworzyć za pomocą tokenu statycznego.

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

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

Tworzenie poświadczeń z wywołaniem zwrotnym

W tym miejscu zakładamy, że mamy funkcję fetchTokenFromMyServerForUser , która wysyła żądanie sieciowe w celu pobrania ciągu tokena JWT dla użytkownika. Przekazujemy go do poświadczeń, aby pobrać token dla Boba z naszego własnego serwera. Nasz serwer będzie używał biblioteki tożsamości komunikacyjnej platformy Azure do wystawiania tokenów. Konieczne jest, aby funkcja zwracała fetchTokenFromMyServerForUser prawidłowy token (z datą wygaśnięcia ustawioną w przyszłości) przez cały czas.

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

Tworzenie poświadczeń z proaktywnym odświeżaniem

Ustawienie refreshProactively wartości true spowoduje wywołanie tokenRefresher funkcji, gdy token jest bliski wygaśnięcia.

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

Tworzenie poświadczeń z proaktywnym odświeżaniem i początkowym tokenem

Przekazywanie initialToken jest opcjonalną optymalizacją w celu pominięcia pierwszego wywołania programu tokenRefresher. Można to użyć do oddzielenia rozruchu od aplikacji od kolejnych cykli odświeżania tokenów.

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

Utwórz poświadczenie z poświadczeniem tokenu, które umożliwia uzyskanie tokenu użytkownika Entra

W przypadku scenariuszy, w których użytkownik Entra może być używany z usługami komunikacyjnymi, należy zainicjować dowolną implementację interfejsu TokenCredential i dostarczyć ją do .EntraCommunicationTokenCredentialOptions Wraz z tym należy podać identyfikator URI zasobu Azure Communication Services i zakresy wymagane dla tokenu użytkownika Entra. Te zakresy określają uprawnienia przyznane tokenowi.

To podejście należy użyć do autoryzowania użytkownika Entra z licencją usługi Teams do korzystania z funkcji rozszerzalności telefonu w usłudze Teams za pośrednictwem zasobu Azure Communication Services. Wymaga to podania https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls zakresu.

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

Inne scenariusze dla użytkowników Entra korzystających z usług Azure Communication Services są obecnie tylko w fazie zapoznawczej i nie powinny być używane w środowisku produkcyjnym. Zakresy tych scenariuszy są zgodne z formatem https://communication.azure.com/clients/<ACS Scope>. Jeśli określone zakresy nie zostaną podane, domyślne zakresy zostaną ustawione 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);

Rozwiązywanie problemów

  • Określono nieprawidłowy token: Upewnij się, że token, który przekazujesz do konstruktora AzureCommunicationTokenCredential lub do wywołania tokenRefresher zwrotnego, jest gołym ciągiem tokenu JWT. Jeśli na przykład używasz biblioteki tożsamości komunikacyjnej platformy Azure lub interfejsu API REST w celu uzyskania tokenu, upewnij się, że przekazujesz tylko token część obiektu odpowiedzi.

Przemysł drzewny

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Dalsze kroki

Wkład

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

  • Last updated on