# @azure/communication-identity 中文文档

规范地址：https://npmcn.com/package/%40azure/communication-identity/

版本：2\.0\.0
npm 元数据更新时间：2026-10-02T05:11:25.276Z
中文译文更新时间：2026-11-07T12:52:50.949Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azure/communication-identity
原文对照：https://npmcn.com/package/%40azure/communication-identity/?lang=original
项目主页：https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/communication/communication-identity/README.md
源码仓库：https://github.com/Azure/azure-sdk-for-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：767 kB，376 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：8 个
- 首次发布：2021-01-27T15:15:19.273Z
- 最新版本发布：2026-10-02T05:11:25.118Z
- 近 30 天下载量：168678（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：442（近 12 个月 57 个）

## 中文简介

SDK用于Azure通信服务,方便用户代号管理.

## 安装

```sh
npm install @azure/communication-identity
```

也可以使用：`pnpm add @azure/communication-identity`、`yarn add @azure/communication-identity`、`bun add @azure/communication-identity`

## README

# JavaScript 的 Azure 通讯身份客户端库

身份库用于管理Azure通信服务的用户和信使.

## 开始

### 先决条件

-   一个 [Azure 订阅](https://azure.microsoft.com/free/)。 。 。 .
-   现有通信服务资源。 如果您需要创建资源, 您可以使用 [Azure 门户](https://portal.azure.com/),则 [Azure 动力壳](https://learn.microsoft.com/powershell/module/az.communication/new-azcommunicationservice),或 [阿苏尔CLI](https://learn.microsoft.com/cli/azure)。 。 。 .

### 安装

```bash
npm install @azure/communication-identity
```

### 浏览器支持

#### Java 脚本套装

要在浏览器中使用此客户端库,首先需要使用捆绑器. 关于如何做到这一点的详情,请参见我们 [捆绑文件](https://aka.ms/AzureSDKBundling)。 。 。 .

## 关键概念

### 客户

这个 `CommunicationIdentityClient` 提供管理用户及其代币的方法.

## 实例

## 认证

您可以从您的通信服务资源中获取密钥和/或连接字符串 [Azure 门户](https://portal.azure.com/)。一旦你有钥匙,就可以认证 `CommunicationIdentityClient` 采用下列任何一种方法:

### 创建 `KeyCredential` 与 `AzureKeyCredential` 在初始化客户端之前

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

### 使用连接字符串

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

### 使用a `TokenCredential`

```ts
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 门户](https://portal.azure.com/)。 。 。 .

## 使用量

### 创建新用户

使用 `createUser` 创建新用户的方法.

```ts
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` (用这个来全程访问Chat API)
-   `voip` (这个可以全程访问API)
-   `chat.join` (访问 Chat API 但无权创建、删除或更新聊天线索)
-   `chat.join.limited` (一个比较有限的聊天版本.join,不允许添加或删除参与者)
-   `voip.join` (进入API但无权开始新电话)

```ts
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"]);
```

要刷新用户令牌,请与同一用户再发一个令牌.

```ts
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小时)的默认值.

```ts
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` 创建新用户,并发布一个函数调用符。 这可以翻译成一个单一的网络请求,而不是先创建用户,再发行一个令牌.

```ts
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小时)的默认值.

```ts
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` 为用户撤销所有已签发的令牌的方法.

```ts
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` 删除用户的方法.

```ts
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` 带有匹配的过期时间.

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

## 解决问题

### 日志

允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 `AZURE_LOG_LEVEL` 环境变量改为 `info`。或者,可以在运行时拨打 `setLogLevel` 输入 `@azure/logger`数字 :

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

setLogLevel("info");
```

## 今后的步骤

请看一下 [样本](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/communication/communication-identity/samples) 关于如何使用此库的详细示例的目录.

## 捐款

如果您想为图书馆捐钱 请读一下 [贡献指南](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) 学习如何构建和测试密码.

## 相关项目

-   [Microsoft Azure SDK 用于 Javascript](https://github.com/Azure/azure-sdk-for-js)

## 常见问题

### @azure/communication-identity 是什么？

SDK用于Azure通信服务,方便用户代号管理\.

### 如何安装 @azure/communication-identity？

在项目目录运行 npm install @azure/communication-identity，或使用 pnpm add / yarn add / bun add。

### @azure/communication-identity 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azure/communication-identity 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azure/communication-identity 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/communication-identity 可以商用吗？

@azure/communication-identity 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azure/communication-identity 的下载量有多少？

根据 npm 官方下载统计，@azure/communication-identity 在 2026/10/08 – 2026/11/06 这 30 天内被下载 168,678 次，日均约 5,623 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azure/communication-identity 还在维护吗？

最新版本 2\.0\.0 发布于 2026/10/02（1 个月前）；至今共发布 442 个版本，其中过去 12 个月发布了 57 个；首次发布于 2021/01/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。