@fluidframework/azure-客户端
Azure-client软件包为与Azure Fluid Relay服务一起消耗协作的Fluid数据提供了简单而强大的方法.
使用 Fluid 框架库
对于依赖流体框架库的公共API,我们建议 ^ (caret)版本范围.
例如,使用 ^1.3.4。 。 。 .
依赖不稳定的API,例如: beta API,我们推荐一个更具限制性的版本范围.
例如,使用一个 ~ 版本范围.
安装
运行此命令以安装软件包 :
npm i @fluidframework/azure-client
从此软件包导入
此软件包使用 packet.json 导出 通过支持级别将API分离. 有关支助保障的信息改为: API 支持级别。 。 。 .
导入 public API 从 @fluidframework/azure-client。 。 。 .
导入 legacy API 从 @fluidframework/azure-client/legacy。 。 。 .
API 文档
读取 @fluidframework/azure-客户端 API 文档 https://fluidframework.com/docs/apis/azure-client 页面存档备份,存于互联网档案馆。 。 。 .
使用 azure 客户端
祖尔客户包有一个 AzureClient 允许你与流体互动的课.
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,将以下命令输入终端窗口:
npx @fluidframework/azure-local-service@latest
现在,随着我们的本地服务运行 在背景,我们需要连接 应用程序与它。 为此,我们首先需要创建我们的 ITokenProvider 实例以认证当前用户对服务。 为此,我们可以使用 InsecureTokenProvider 其中我们可以将任何东西传递到密钥中(因为我们正在本地运行)和一个识别当前用户的对象。 我们的端点 URL 将指向我们本地 Azure Fluid Relay 服务实例正在运行的域和端口 。 最后,为了区分本地模式和远程模式,我们设置了 type 改为 "local" 或者说 "remote" 页:1.
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映射到一个租户密钥来生成并签名使服务接受.
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 支持具有实验特性的即时处理能力.
这些特征具有实验性质,应当 没有 用于生产应用.
要学更多,看 实验特征。 。 。 .
流体容器
集装箱实例是流体内部的一个组织单位。 每个容器实例都与定义的流体服务连接,并包含协作对象集合.
集装箱由独特的身份证创建和识别。 这些ID的管理和存储由开发者负责.
界定流体容器
流体容器由一个计划定义。 计划包括集装箱的初始特性以及能够动态生成哪些协作对象.
见 ContainerSchema 内 ./src/types/ts 关于具体属性的细节.
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需要连接到服务器上,所以容器需要同步创建并取回.
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 财产的签名与集装箱计划相同.
// 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 可装入对象上的属性.
动态对象按需要加载,以优化数据虚拟化. 要得到可装入对象,首先得到存储的手柄,然后解决那个手柄.
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同时收到 上游支助。 。 。 .
- 流体框架将停止支持第22版 当上游支持于2027-04-30结束时。 。 。 .
- 流体框架不支持节点.js与
--no-experimental-fetch旗帜.
- Fluid框架支持支持ES2022标准库的现代浏览器.
支持的工具
- 类型脚本 6.0数字 :
- 流体框架支持全部
strict选项. - 设定建设目标(
lib, (中文(简体) ),target改为:ES2022或后会. - 启用
strictNullChecks。 。 。 . - 流体框架不支持 在 TypeScript 6.0 中贬值的配置选项。 。 。 .
- 流体框架不完全支持
exactOptionalPropertyTypes。 。 。 . 如果您启用此选项, 请不要使用in, (中文(简体) ),Reflect.has, (中文(简体) ),Object.hasOwn,或Object.prototype.hasOwnProperty改为Fluid框架类型的窄成员. 这些方法可以错误地排除undefined从可能的值.
- 流体框架支持全部
- 网络软件包 页:1
- 我们不需要一个特定的捆绑者. 其他处理ES模块的捆绑机可以工作,但我们只积极测试网页包.
模块分辨率
在类型脚本中 compilerOptions,使用时 Node16, (中文(简体) ), Node20, (中文(简体) ), NodeNext,或 Bundler 模块分辨率.
这些设置遵循 节点.js v12+无害环境管理 分辨率和加载算法。 。 。 .
不使用 Node10 模块分辨率.
模块格式
- ES模块: 使用ES模块来消耗Fluid框架客户端软件包,包括在Node.js中.
- 常见JS : Fluid Framework在3.0版本或后期不正式支持CommonJS.
贡献准则
你们可以 贡献 通过这些方式实现流体框架:
详细指示改为: repo 文档。 。 。 .
本项目遵循 Microsoft 开源行为守则。 。 。 . 更多信息,改为: 《行为守则》经常被问到的问题。 。 。 . 问题或评论,联系 打开码@ microsoft.com。 。 。 .
这个项目可能包含微软项目的商标或标志,产品,或服务. 这些商标或标志的使用必须遵循微软 商标和品牌准则。 。 。 . 在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.
帮助
读取 流体框架文件 用于了解流体框架概念和API.
要求提供文件未载列的资料, 创建问题。 。 。 .
商标
这个项目可能包含微软项目的商标或标志,产品,或服务.
这些商标或标志的使用必须遵循微软的 商标和品牌准则。 。 。 .
在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.