你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure 通信通用客户端库 - 版本 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 ：

静态令牌（适用于用于发送一次性 Chat 消息等的短期客户端）或
一个回调函数，可确保通信期间的持续身份验证状态（例如，非常适合长时间的 Calling 会话）。
能够获取 Entra 用户令牌的令牌凭证。您可以提供 TokenCredential 接口的任何实现。它适用于需要 Entra 用户访问令牌才能使用通信服务进行身份验证的方案。

可以通过构造函数或令牌刷新程序回调向 AzureCommunicationTokenCredential 提供的令牌可以使用 Azure 通信标识库获取。

例子

使用静态令牌创建凭证

对于生存期较短的客户端，无需在过期时刷新令牌，并且可以 AzureCommunicationTokenCredential 使用静态令牌进行实例化。

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

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

使用回调创建凭证

在这里，我们假设我们有一个函数，该函数 fetchTokenFromMyServerForUser 发出网络请求来检索用户的 JWT 令牌字符串。我们将其传递到凭证中，以从我们自己的服务器获取 Bob 的令牌。我们的服务器将使用 Azure 通信标识库来颁发令牌。该 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("bob@contoso.com"),
});

使用主动刷新创建凭据

设置为 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("bob@contoso.com"),
  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("bob@contoso.com"),
  refreshProactively: true,
  token:
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
});

使用能够获取 Entra 用户令牌的令牌凭证创建凭证

对于 Entra 用户可以与通信服务一起使用的方案，您需要初始化 TokenCredential 接口的任何实现，并将其提供给 EntraCommunicationTokenCredentialOptions. 除此之外，还必须提供 Azure 通信服务资源的 URI 和 Entra 用户令牌所需的范围。这些范围确定授予令牌的权限。

此方法需要用于授权具有 Teams 许可证的 Entra 用户通过 Azure 通信服务资源使用 Teams 电话扩展性功能。这需要提供 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);

Entra 用户使用 Azure 通信服务的其他方案目前 仅处于预览阶段，不应用于生产。这些方案的范围遵循格式 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 通信标识库或 REST API 获取令牌，请确保仅 token 传递响应对象的部分。

伐木业

启用日志记录可能有助于发现有关故障的有用信息。若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。或者，可以通过在 setLogLevel中调用 @azure/logger 在运行时启用日志记录：

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

setLogLevel("info");

后续步骤

详细了解通信用户访问令牌

贡献

若要参与此库，请阅读贡献指南了解有关如何生成和测试代码的详细信息。

适用于 Javascript 的 Microsoft Azure SDK

通过