# @fluidframework/azure-client 中文文档

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

版本：3\.12\.0
npm 元数据更新时间：2026-11-10T23:02:29.572Z
中文译文更新时间：2026-11-15T01:53:33.911Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fluidframework/azure-client
原文对照：https://npmcn.com/package/%40fluidframework/azure-client/?lang=original
项目主页：https://fluidframework.com/
源码仓库：https://github.com/microsoft/FluidFramework

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

- 包体积（解压后）：252 kB，81 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2021-08-20T23:11:21.482Z
- 最新版本发布：2026-11-10T23:02:29.399Z
- 近 30 天下载量：53913（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：438（近 12 个月 48 个）

## 中文简介

使用 Azure 流体中继服务创建和装载流体容器的工具

## 安装

```sh
npm install @fluidframework/azure-client
```

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

## README

# @fluidframework/azure-客户端

Azure-client软件包为与Azure Fluid Relay服务一起消耗协作的Fluid数据提供了简单而强大的方法.

## 使用 Fluid 框架库

对于依赖流体框架库的公共API,我们建议 `^` (caret)版本范围. 例如,使用 `^1.3.4`。 。 。 .

依赖不稳定的API,例如: `beta` API,我们推荐一个更具限制性的版本范围. 例如,使用一个 `~` 版本范围.

## 安装

运行此命令以安装软件包 :

```bash
npm i @fluidframework/azure-client
```

## 从此软件包导入

此软件包使用 [packet.json 导出](https://nodejs.org/api/packages.html#exports) 通过支持级别将API分离. 有关支助保障的信息改为: [API 支持级别](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels)。 。 。 .

导入 `public` API 从 `@fluidframework/azure-client`。 。 。 .

导入 `legacy` API 从 `@fluidframework/azure-client/legacy`。 。 。 .

## API 文档

读取 **@fluidframework/azure-客户端** API 文档 [https://fluidframework.com/docs/apis/azure-client 页面存档备份,存于互联网档案馆](https://fluidframework.com/docs/apis/azure-client)。 。 。 .

## 使用 azure 客户端

祖尔客户包有一个 `AzureClient` 允许你与流体互动的课.

```typescript
import { AzureClient } from "@fluidframework/azure-client";
```

## 证明 AzureClient

Fluid需要支持服务,以便进行协作交流。 这个 `AzureClient` 既支持针对已部署的Azure Fluid中继服务生产情景进行即时处理,也支持针对来自本地的即时处理服务实例 `@fluidframework/azure-local-service` 图书馆,用于发展目的.

注:您可以使用一个实例 `AzureClient` 从同一个 Azure Fluid Relay 服务实例创建/牵引多个容器.

在下面的例子中,我们将通过提供租户身份证和我们登上服务时独有的钥匙来连接一个活的Azure Fluid Relay服务实例,以及一个将我们的应用程序与本地服务运行的例子。 我们利用 `AzureFunctionTokenProvider` 用于代号生成,同时运行在活的 Azure 流体中继实例和 `InsecureTokenProvider`从 `@fluidframework/test-client-utils` 软件包,可以认证给定用户对本地服务的访问。 这个 `AzureFunctionTokenProvider` 实现 `ITokenProvider` 界面,但不披露客户端代码中的租户密钥.

### 本地备份

用默认值运行本地 Azure 流体中继服务 `localhost:7070`,将以下命令输入终端窗口:

```sh
npx @fluidframework/azure-local-service@latest
```

现在,随着我们的本地服务运行 在背景,我们需要连接 应用程序与它。 为此,我们首先需要创建我们的 `ITokenProvider` 实例以认证当前用户对服务。 为此,我们可以使用 `InsecureTokenProvider` 其中我们可以将任何东西传递到密钥中(因为我们正在本地运行)和一个识别当前用户的对象。 我们的端点 URL 将指向我们本地 Azure Fluid Relay 服务实例正在运行的域和端口 。 最后,为了区分本地模式和远程模式,我们设置了 `type` 改为 `"local"` 或者说 `"remote"` 页:1.

```typescript
import { AzureClient, AzureConnectionConfig } from "@fluidframework/azure-client";
import { InsecureTokenProvider } from "@fluidframework/test-client-utils";

const clientProps = {
    connection: {
        type: "local",
        tokenProvider: new InsecureTokenProvider("fooBar", { id: "123", name: "Test User" }),
        endpoint: "http://localhost:7070",
    },
};
const azureClient = new AzureClient(clientProps);
```

### 由活的 Azure 流体中继实例支持

当运行在活的 Azure Fluid Relay 实例上时, 我们可以使用与本地相同的界面, 但使用租户ID, 订购器, 和存储 URL, 这些都是作为 Azure Fluid Relay 上载过程的一部分提供的 。 为了保证这个秘密不被曝光,它被传递到一个安全,后端的Azure函数上,从中取出该令牌. 我们通过 Azure 函数 URL,由 `/api/GetAzureToken` 与当前用户对象一起 `AzureFunctionTokenProvider`。稍后,在 `AzureFunctionTokenProvider` 我们做一个轴 `GET` 请求调用 Azure 函数,方法是通过在租户ID、文档Id 和 id/name 作为可选参数。 Azure功能负责将租户ID映射到一个租户密钥来生成并签名使服务接受.

```typescript
import { AzureClient, AzureConnectionConfig } from "@fluidframework/azure-client";

const clientProps = {
    connection: {
        type: "remote",
        tenantId: "YOUR-TENANT-ID-HERE",
        tokenProvider: new AzureFunctionTokenProvider("AZURE-FUNCTION-URL" + "/api/GetAzureToken", {
            id: "test-user",
            name: "Test User",
        }),
        endpoint: "ENTER-SERVICE-DISCOVERY-URL-HERE",
    },
};
const azureClient = new AzureClient(clientProps);
```

### 实验特征

`AzureClient` 支持具有实验特性的即时处理能力. 这些特征具有实验性质,应当 **没有** 用于生产应用. 要学更多,看 [实验特征](https://fluidframework.com/docs/build/experimental-features/)。 。 。 .

## 流体容器

集装箱实例是流体内部的一个组织单位。 每个容器实例都与定义的流体服务连接,并包含协作对象集合.

集装箱由独特的身份证创建和识别。 这些ID的管理和存储由开发者负责.

## 界定流体容器

流体容器由一个计划定义。 计划包括集装箱的初始特性以及能够动态生成哪些协作对象.

见 [`ContainerSchema`](https://npmcn.com/package/%40fluidframework/azure-client/src/types.ts) 内 [`./src/types/ts`](https://npmcn.com/package/%40fluidframework/azure-client/src/types.ts) 关于具体属性的细节.

```typescript
const schema = {
    initialObjects: {
        /* ... */
    },
    dynamicObjectTypes: [
        /*...*/
    ],
};
const azureClient = new AzureClient(props);
const { container, services } = await azureClient.createContainer(schema, "2.100.0" /* oldestSupportedClient */);

// Set any default data on the container's `initialObjects` before attaching
// Returned ID can be used to fetch the container via `getContainer` below
const id = await container.attach();
```

## 使用流体容器

使用 `AzureClient` 对象,开发者可以创建和获取流体容器。 因为Fluid需要连接到服务器上,所以容器需要同步创建并取回.

```typescript
import { AzureClient } from "@fluidframework/azure-client";

const azureClient = new AzureClient(props);
const { container, services } = await azureClient.getContainer("_unique-id_", schema, "2.100.0" /* oldestSupportedClient */);
```

**说明:** 使用时 `AzureClient` 与 `tenantId` 设置为 `"local"`,所有已创建的容器,当从终端窗口运行的本地 Azure Fluid Relay 服务实例(不是客户端)被关闭时,将会被删除。 然而,在对远程Azure Fluid Relay服务运行时所创建的任何容器都将被坚持. 集装箱身份证 **无法** 在本地和远程的Azure Fluid Relay服务之间重新使用,以获取同一容器.

## 使用初始对象

最常见的使用流体的方法是通过创建容器时创建的初始合作对象. 分布式DataStructures和Data Objects都是被支持的合作对象类型.

`initialObjects` 集装箱装入内存后,开发者可通过集装箱进入 `initialObjects` 属性。 这个 `initialObjects` 财产的签名与集装箱计划相同.

```typescript
// Define the keys and types of the initial list of collaborative objects.
// Here, we are using a SharedMap DDS on key "map1" and a SharedString on key "text1".
const schema = {
    initialObjects: {
        map1: SharedMap,
        text1: SharedString,
    },
};

// Fetch back the container that had been created earlier with the same ID and schema
const { container, services } = await azureClient.getContainer("_unique-id_", schema, "2.100.0" /* oldestSupportedClient */);

// Get our list of initial objects that we had defined in the schema. initialObjects here will have the same signature
const initialObjects = container.initialObjects;
// Use the keys that we had set in the schema to load the individual objects
const map1 = initialObjects.map1;
const text1 = initialObjects["text1"];
```

## 使用动态对象

可装入对象也可以在运行期间动态创建. 动态对象类型需要在 `dynamicObjectTypes` 集装箱计划的财产.

集装箱有一个 `create` 用于创建新类型实例的方法。 此实例会是用户的本地端, 直到附加到另一个可装入对象上 。 这样创建的动态对象应被存储在初始对象中,初始对象在创建容器时被附加. 当存储可装入对象时,您必须存储对象而不是对象本身的引用 。 为了做到这一点,使用 `handle` 可装入对象上的属性.

动态对象按需要加载,以优化数据虚拟化. 要得到可装入对象,首先得到存储的手柄,然后解决那个手柄.

```typescript
const schema = {
    initialObjects: {
        map1: SharedMap,
    },
    dynamicObjectTypes: [SharedString],
};

const { container, services } = await azureClient.getContainer("_unique-id_", schema, "2.100.0" /* oldestSupportedClient */);
const map1 = container.initialObjects.map1;

const text1 = await container.create(SharedString);
map1.set("text1-unique-id", text1.handle);

// ...

const text1Handle = map1.get("text1-unique-id"); // Get the handle
const text1 = await map1.get(); // Resolve the handle to get the object

// or

const text1 = await map1.get("text1-unique-id").get();
```

## 客户最低要求

Fluid框架客户端库支持此文档中的平台. 这些要求有意具有限制性. 在一个主要的版本系列中,我们可以放松这些要求,但我们不能使其更严格. 对于长期支持(LTS)版本,我们可能需要支持这些平台几年.

其他配置可以奏效,但Fluid框架不支持. 如果一个不支持的配置停止工作, 我们不会将此归类为错误 . 要请求支持未列出的配置, 请存档 . 产品组会评估你的要求. 在此问题上,请具体说明配置的现状:

-   配置有效但需要官方支持.
-   配置不起作用,需要更改.

### 支持的运行时间

-   Fluid框架支持节点.js版本22和24同时收到 [上游支助](https://nodejs.org/en/about/previous-releases)。 。 。 .
    -   流体框架将停止支持第22版 [当上游支持于2027-04-30结束时](https://github.com/nodejs/release#release-schedule)。 。 。 .
    -   流体框架不支持节点.js与 `--no-experimental-fetch` 旗帜.
-   Fluid框架支持支持ES2022标准库的现代浏览器.

### 支持的工具

-   [类型脚本 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0)数字 :
    -   流体框架支持全部 [`strict`](https://www.typescriptlang.org/tsconfig) 选项.
    -   设定建设目标(`lib`, (中文(简体) ), `target`改为: `ES2022` 或后会.
    -   启用 [`strictNullChecks`](https://www.typescriptlang.org/tsconfig)。 。 。 .
    -   流体框架不支持 [在 TypeScript 6.0 中贬值的配置选项](https://typescriptdocs.com/release-notes/TypeScript%206.0#breaking-changes-and-deprecations-in-typescript-6-0)。 。 。 .
    -   流体框架不完全支持 `exactOptionalPropertyTypes`。 。 。 . 如果您启用此选项, 请不要使用 `in`, (中文(简体) ), `Reflect.has`, (中文(简体) ), `Object.hasOwn`,或 `Object.prototype.hasOwnProperty` 改为Fluid框架类型的窄成员. 这些方法可以错误地排除 `undefined` 从可能的值.
-   [网络软件包](https://webpack.js.org/) 页:1
    -   我们不需要一个特定的捆绑者. 其他处理ES模块的捆绑机可以工作,但我们只积极测试网页包.

### 模块分辨率

在类型脚本中 `compilerOptions`,使用时 [`Node16`, (中文(简体) ), `Node20`, (中文(简体) ), `NodeNext`,或 `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) 模块分辨率. 这些设置遵循 [节点.js v12+无害环境管理 分辨率和加载算法](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm)。 。 。 .

不使用 `Node10` 模块分辨率.

### 模块格式

-   ES模块: 使用ES模块来消耗Fluid框架客户端软件包,包括在Node.js中.
-   常见JS : Fluid Framework在3.0版本或后期不正式支持CommonJS.

## 贡献准则

你们可以 [贡献](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) 通过这些方式实现流体框架:

-   回答问题 [GitHub 讨论](https://github.com/microsoft/FluidFramework/discussions)。 。 。 .
-   [提交错误报告](https://github.com/microsoft/FluidFramework/issues) 并且帮助验证修正.
-   审查 [源代码更改](https://github.com/microsoft/FluidFramework/pulls)。 。 。 .
-   [贡献错误修正](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md)。 。 。 .

详细指示改为: [repo 文档](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md)。 。 。 .

本项目遵循 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息,改为: [《行为守则》经常被问到的问题](https://opensource.microsoft.com/codeofconduct/faq/)。 。 。 . 问题或评论,联系 [打开码@ microsoft.com](mailto:opencode@microsoft.com)。 。 。 .

这个项目可能包含微软项目的商标或标志,产品,或服务. 这些商标或标志的使用必须遵循微软 [商标和品牌准则](https://www.microsoft.com/trademarks)。 。 。 . 在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.

## 帮助

读取 [流体框架文件](https://fluidframework.com/docs/) 用于了解流体框架概念和API.

要求提供文件未载列的资料, [创建问题](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md)。 。 。 .

## 商标

这个项目可能包含微软项目的商标或标志,产品,或服务.

这些商标或标志的使用必须遵循微软的 [商标和品牌准则](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general)。 。 。 .

在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.

## 常见问题

### @fluidframework/azure-client 是什么？

使用 Azure 流体中继服务创建和装载流体容器的工具

### 如何安装 @fluidframework/azure-client？

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

### @fluidframework/azure-client 支持 TypeScript 吗？

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

### @fluidframework/azure-client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fluidframework/azure-client 可以商用吗？

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

### @fluidframework/azure-client 的下载量有多少？

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

### @fluidframework/azure-client 还在维护吗？

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