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

Azure Communication Identity client library for JavaScript - version 2.0.0

身份库用于管理Azure 通信服务的用户和令牌。

入门

Prerequisites

Azure 订阅。
现有的通信服务资源。如果需要创建资源，可以使用 Azure 门户、Azure PowerShell或 Azure CLI。

安装

npm install @azure/communication-identity

浏览器支持

JavaScript 捆绑包

若要在浏览器中使用此客户端库，首先需要使用捆绑程序。有关如何执行此操作的详细信息，请参阅我们的捆绑文档。

重要概念

Clients

它 CommunicationIdentityClient 提供了管理用户及其代币的方法。

Examples

Authentication

你可以在Azure 门户从通信服务资源获得密钥和/或连接字符串。一旦你有了密钥，可以使用以下任一方法进行 CommunicationIdentityClient 认证：

在初始化客户端之前先创建`KeyCredentialAzureKeyCredential`

import { AzureKeyCredential } from "@azure/core-auth";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const key = "<some-key>";
const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new AzureKeyCredential(key);
const client = new CommunicationIdentityClient(endpoint, credential);

使用连接字符串

import { CommunicationIdentityClient } from "@azure/communication-identity";

// Example connection string
const connectionString =
  "endpoint=https://contoso.eastus.communications.azure.net/;accesskey=secret";

const client = new CommunicationIdentityClient(connectionString);

使用 `TokenCredential`

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

如果使用密钥初始化客户端，则还需要提供相应的终结点。可以从 Azure 门户中的通信服务资源获取此终结点。

Usage

创建新用户

使用该 createUser 方法创建新用户。

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const user = await client.createUser();

创建和刷新用户令牌

使用该 getToken 方法为现有用户发行或刷新令牌。该方法还会接收通信令牌范围的列表。范围选项包括：

chat （使用此以获得对聊天API的全面访问）
voip （使用此权限可完全访问调用API）
chat.join （访问聊天 API，但无授权创建、删除或更新聊天线程）
chat.join.limited （chat.join 的更有限版本，不允许添加或移除参与者）
voip.join （访问调用API，但无需授权启动新调用）

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const user = await client.createUser();

const { token } = await client.getToken(user, ["chat"]);

要刷新用户令牌，需用同一用户再发一个令牌。

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const user = await client.createUser();

let { token } = await client.getToken(user, ["chat"]);

// Refresh the token again
({ token } = await client.getToken(user, ["chat"]));

创建带有自定义到期期限的用户令牌

也可以通过自定义到期时间来创建通信身份访问令牌。代币的有效期必须在[60,1440]分钟范围内。如果未提供，将使用默认值1440分钟（24小时）。

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const user = await client.createUser();

const tokenOptions = { tokenExpiresInMinutes: 60 };
const { token } = await client.getToken(user, ["chat"], tokenOptions);

在单一请求中创建用户和令牌

为了方便起见，使用 createUserAndToken 创建一个新用户并通过一个函数调用发放令牌。这转化为一个网页请求，而不是先创建用户再发放令牌。

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const { user, token } = await client.createUserAndToken(["chat"]);

在一个请求中创建用户和带有自定义到期期限的令牌

也可以通过自定义到期时间来创建通信身份访问令牌。代币的有效期必须在[60,1440]分钟范围内。如果未提供，将使用默认值1440分钟（24小时）。

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const userAndTokenOptions = { tokenExpiresInMinutes: 60 };
const { user, token } = await client.createUserAndToken(["chat"], userAndTokenOptions);

为用户撤销代币

使用该 revokeTokens 方法来撤销用户所有已发行的代币。

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

// Create user
const user = await client.createUser();

// Later when you want to revoke the user's tokens
await client.revokeTokens(user);

删除用户

使用 deleteUser 该方法删除用户。

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

// Create user
const user = await client.createUser();

// Later when you want to delete the user
await client.deleteUser(user);

将Teams用户的Azure AD访问令牌交换为通信访问令牌

使用getTokenForTeamsUser方法将 Teams 用户的 Azure AD 访问令牌换成CommunicationAccessToken一个有效期匹配的新令牌。

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const { token, expiresOn } = await client.getTokenForTeamsUser({
  teamsUserAadToken: "<aad-access-token-of-a-teams-user>",
  clientId: "<cliend-id-of-an-aad-application>",
  userObjectId: "<aad-object-id-of-a-teams-user>",
});

Troubleshooting

Logging

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

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

setLogLevel("info");

后续步骤

有关如何使用此库的详细示例，请查看示例目录。

Contributing

如果你想为本库贡献内容，请阅读贡献指南，了解更多关于如何构建和测试代码的信息。

适用于 Javascript 的 Microsoft Azure SDK

反馈

此页面是否有帮助？

上次更新时间为 2026-10-02