Общая клиентская библиотека Azure Communication для JavaScript версии 2.4.0

2025-06-06

Этот пакет содержит общий код для библиотек Службы коммуникации Azure.

Начало работы

Предпосылки

Подписка Azure.
Существующий ресурс служб коммуникации. Если необходимо создать ресурс, можно использовать портал Azure, Azure PowerShellили Azure CLI.
Установив пакет.@azure/identity

Установка

npm install @azure/communication-common

npm install @azure/identity

Поддержка веб-браузеров

Пакет JavaScript

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. Дополнительные сведения о том, как это сделать, см. в нашей документации по .

Основные понятия

CommunicationTokenCredential и AzureCommunicationTokenCredential

Это CommunicationTokenCredential интерфейс, используемый для аутентификации пользователя с помощью служб связи, таких как чат или звонки.

Он AzureCommunicationTokenCredential предлагает удобный способ создания учетных данных, реализующих указанный интерфейс, и позволяет воспользоваться встроенной логикой автоматического обновления.

В зависимости от сценария может потребоваться инициализация AzureCommunicationTokenCredential с помощью:

статический токен (подходит для краткосрочных клиентов, используемых, например, для отправки разовых сообщений в чате) или
функция обратного вызова, которая обеспечивает непрерывное состояние аутентификации во время коммуникаций (идеально, например, для длительных сеансов Calling).
учетные данные токена, позволяющие получить токен пользователя Entra. Вы можете предоставить любую реализацию интерфейса TokenCredential. Он подходит для сценариев, в которых для аутентификации в службах коммуникации требуются маркеры доступа пользователей Entra.

Токены, предоставленные либо AzureCommunicationTokenCredential через конструктор, либо через обратный вызов обновления маркеров, можно получить с помощью библиотеки Azure Communication Identity.

Примеры

Создание учетных данных с помощью статического маркера

Для кратковременно живущих клиентов нет необходимости обновлять токен по истечении срока действия, и его AzureCommunicationTokenCredential экземпляр может быть реализован с помощью статического токена.

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

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

Создание учетных данных с помощью обратного вызова

Здесь мы предполагаем, что у нас есть функция fetchTokenFromMyServerForUser , которая делает сетевой запрос для получения строки токена JWT для пользователя. Мы передаем его в учетные данные, чтобы получить токен для Боба с нашего собственного сервера. Наш сервер будет использовать библиотеку Azure Communication Identity для выпуска токенов. Необходимо, чтобы fetchTokenFromMyServerForUser функция всегда возвращала действительный токен (с датой истечения срока действия, установленной в будущем).

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("[email protected]"),
});

Создание учетных данных с упреждающим обновлением

Установка refreshProactively значения true вызовет вашу tokenRefresher функцию, когда срок действия токена близится к истечению.

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("[email protected]"),
  refreshProactively: true,
});

Создание учетных данных с упреждающим обновлением и начальным маркером

Передача initialToken — это необязательная оптимизация, позволяющая пропустить первый вызов tokenRefresher. Это можно использовать для отделения загрузки от приложения от последующих циклов обновления маркеров.

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("[email protected]"),
  refreshProactively: true,
  token:
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
});

Создание учетных данных с помощью учетных данных маркера, способных получить токен пользователя Entra

Для сценариев, в которых пользователь Entra может использоваться с Communication Services, необходимо инициализировать любую реализацию интерфейса TokenCredential и предоставить ее .EntraCommunicationTokenCredentialOptions Наряду с этим необходимо предоставить универсальный код ресурса Azure Communication Services и области, необходимые для токена пользователя Entra. Эти области определяют разрешения, предоставляемые маркеру.

Этот подход необходимо использовать для авторизации пользователя Entra с лицензией Teams для использования функций расширения телефона Teams через ресурс Служб коммуникации Azure. Для этого необходимо предоставить 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);

Другие сценарии использования Служб коммуникации Azure пользователями Entra в настоящее время находятся только на стадии предварительной версии и не должны использоваться в рабочей среде. Области для этих сценариев имеют следующий формат https://communication.azure.com/clients/<ACS Scope>. Если конкретные области не указаны, области по умолчанию будут установлены в 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);

Устранение неполадок

Указан недопустимый токен: убедитесь, что токен, который вы передаете конструктору AzureCommunicationTokenCredential или обратному tokenRefresher вызову, является голой строкой токена JWT. Например, если вы используете библиотеку Azure Communication Identity или REST API для получения маркера, убедитесь, что вы передаете только token часть объекта ответа.

Лесозаготовка

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. В альтернативном порядке, логирование можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

Дальнейшие шаги

Подробнее о Токены доступа пользователей связи

Вклад

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.

Пакет SDK Microsoft Azure для JavaScript