# @ariestools/aries-datalake-client 中文文档

规范地址：https://npmcn.com/package/%40ariestools/aries-datalake-client/

版本：0\.3\.1
npm 元数据更新时间：2026-10-30T20:13:32.060Z
中文译文更新时间：2026-11-08T01:11:53.253Z
软件包许可：LGPL-3\.0-only

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

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

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

- 包体积（解压后）：1.2 MB，199 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26
- 运行依赖：7 个
- peer 依赖：@opentelemetry/api ^1\.10，@ariestools/cli-kit-daemon ^2\.1
- 首次发布：2026-07-21T19:07:48.832Z
- 最新版本发布：2026-10-30T20:13:31.834Z
- 近 30 天下载量：1945（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

Aries 点播 XL1 数据湖控制平面的客户端 SDK

## 安装

```sh
npm install @ariestools/aries-datalake-client
```

也可以使用：`pnpm add @ariestools/aries-datalake-client`、`yarn add @ariestools/aries-datalake-client`、`bun add @ariestools/aries-datalake-client`

## README

# `@ariestools/aries-datalake-client`

Aries datalake控取和数据平面的REST客户端,只有节点本地开发帮助器保留在节点入口后.

## 入境点

-   `@ariestools/aries-datalake-client` 是节点入口。 它包括REST客户端加上本地文件系统支持的客户端,证书,默认,以及 `ARIES_HOME` 帮手.
-   `@ariestools/aries-datalake-client/browser` 是浏览器的入口。 它会输出REST客户端,复合客户端,他们的界面,同步的代号-供应商合同,以及浏览器安全的数据湖电线合同.

使用针对每项请求的同步令牌供应商。 应用程序适配器可能通过XL1浏览器钱包网关从页面内存中还原一个仍然有效的短寿命符号,或请求新钱包JWT:

```ts
import {
  RestDatalakeClient,
  RestPayloadsClient,
} from '@ariestools/aries-datalake-client/browser'

// Application-supplied adapter around the installed XL1 wallet gateway.
// The wallet derives and signs the browser origin; the page does not supply it.
declare function requestWalletJwt(audience: string): Promise<string>

const authToken = async ({ audience }: { audience: string }): Promise<string> => {
  return await requestWalletJwt(audience)
}

const control = new RestDatalakeClient({
  baseUrl: 'https://control.example',
  authToken,
})

const payloads = new RestPayloadsClient({
  baseUrl: 'https://data.example',
  datalakeId: 'dl_example',
  authToken,
})
```

供应商接收精确的控制飞机受众或datalake id. 将它的返回值视为敏感而短命的无记名符号:在有用时只将其缓存到页面内存中,在浏览器存储或日志中绝不坚持. 钱包网关控制密钥访问;Aries HTTP服务独立验证受众,签名,来源,范围,签名人身份,以及活的ACL状态.

## 精确根数档案

`ExactRootArchive` 可从两个条目中找到。 提供明确的本地 SDK root- 身份调用, 配置散列域和湖, 仅信任附件 和所有六个正限限制: 根数、 请求字节、 解码 响应字节、符号字节、全操作毫秒和并行工作. 客户端抓取JSON身体,验证原生根,发送原生插入 请求,然后通过匿名独立解决每个需要的根 重新校正,并删除证书,拒绝重定向。 复制收据 从不替换回读。 没有写入缓存、队列、自动重试或恢复日记 介绍.

对于选入服务-Wallet简介,发行人以湖编号签署JWT 它的确切受众和 `payloadScopes: ['payload:append']`浏览器 来源/范围或记录/blob 索赔。 数据平面必须明确启用服务 钱包 JWTs 和 签名人必须持有一个活跑者补助金。 现场观众 独立发放回程许可。 没有 `payloadScopes` 保留 传统服务权,不限定这种有限身份.

`ExactRootArchiveError` 报告无秘密密码和 `writeState`数字 : `not-started`, (中文(简体) ), `uncertain` 发送后,或 `acknowledged` hTTP 成功后. 每一次公共失败都是新错误,有经过验证的代码和捕获的写法 状态; 放弃回调消息、 原因和私人收据。 打电话的人 超时不会取消存储 。 待召回/效应 在他们和解之前,即使被呼叫者收到取消通知之后,也要使用货币. 后期反应机构被取消,本地流取消清理 等待该插槽发布;挂接清理保持容量占用 . 字节限制计算 UTF-8 JSON 请求并解码响应流,包括 出错; 原始网络/解压缩/标题/chunk 分配限制属于 信任的主机运输. 受信任的发行商 单独约束自己的运输, 返回未登录/保存的证书,并尊重所提供的中止信号. 身份回调保存客户端/应用程序字段并使用自有 存储元数据 SDK 投影; 声称的散列永远不是证据 .

## 多个需要的数据湖

`CompositePayloadsClient` 写入每个目标的合格子集,并通过 读取内容返回。 在选中的边上配置完整的 S3 收藏 使用已认证的自动驱动收藏 `RestPayloadsClient` 实例 :

```ts
import { CompositePayloadsClient, type RestPayloadsClient } from '@ariestools/aries-datalake-client/browser'
import { asAnyPayload, PayloadBuilder } from '@xyo-network/sdk'

declare const autoDriveClient: RestPayloadsClient
declare const s3Client: RestPayloadsClient

const composite = new CompositePayloadsClient({
  identify: async (payload) => {
    const canonical = asAnyPayload(payload, true)
    return {
      hash: await PayloadBuilder.hash(canonical),
      dataHash: await PayloadBuilder.dataHash(canonical),
    }
  },
  targets: [
    {
      name: 'auto-drive',
      client: autoDriveClient,
      policy: {
        mode: 'selected',
        allowedSchemas: ['com.example.smallrecord'],
        maxPayloadBytes: 4096, // Example deployment limit, not a provider default.
        revision: 'v1',
      },
    },
    { name: 's3', client: s3Client, policy: { mode: 'all' } },
  ],
})

const result = await composite.insertWithReceipts([
  { schema: 'com.example.smallrecord', value: 1 },
  { schema: 'com.example.other', value: 2 },
])
const read = await composite.getWithReceipts(result.acknowledged.map(payload => payload._hash))
```

所有目标都需要符合其资格的子集。 需要选定政策 一个明确的允许列表和正字节限制;一个空列表不选择任何东西. `disallowedSchemas` 以优先为准. `schemaMaxPayloadBytes` 可能会收紧 全球字节限制,以及 `isValid` 可提供可信任的结构验证器. 大小计算 UTF-8 JSON 包括客户端元数据,不包括存储元数据. 接收服务必须独立执行政策;该客户不 授权永久上传或执行服务配额.

`insert(payloads)` 返回已核实的确认数组,包括重复; `insertWithReceipts(payloads)` 还返回每个目标的资格和结果. 被拒绝的预期合格项目或失败的所需目标投出 `CompositePayloadsWriteError`。 。 `result` 保留经核实的部分成功 消毒收据,而不是原始供应商错误。 完全目标的成功不会 满足不同目标的义务。 呼叫者拥有持久的重试状态 政策修改协调; 该客户端不会恢复失败的操作.

`get(hashes)` 财务报告和审定财务报表 `getMany(hashes)` 返回已核实的有效载荷阵列. `getWithReceipts(hashes)` 增加源属性. 读取在声明中尝试目标 仅命令未解决的散列。 提供者错误或腐败反应 `CompositePayloadsReadError`它们不会默默地变成缺失. 读者从不复制目标之间的内容. 供应犬XYO `PayloadBuilder` 铺开 `identify`; 复合包本身未添加 XYO 运行时间 依赖浏览器消费者.

只有平平的有效载荷被接受。 鉴定和平整已知水分 插入前的协议信封。 没有全球序列,清晰,删除, 或使用 API,并且没有自动注册到 XL1 连接。 这个 有效载荷阵列 `insert`编号 :`get` 用于协议适配器的方法; 保存 sDK的准确交易内容 承认在适配器. 成功的回读是可读存储,而不是提供者网络存档的证明.

## 明确公用有效载荷读取

使用 `RestPublicPayloadsReader` 当提供商允许公众观看时 到数据湖。 这与上面认证的客户端分开; a 认证失败永远不会触发匿名重试 .

```ts
import { RestPublicPayloadsReader } from '@ariestools/aries-datalake-client/browser'

const reader = new RestPublicPayloadsReader({
  baseUrl: 'https://data.example/plane/v1/datalakes/dl_public',
  datalakeId: 'dl_public',
})
const controller = new AbortController()
const payload = await reader.get('configured-content-hash', {
  maxResponseBytes: 65_536,
  signal: controller.signal,
})
```

读者只揭露 `get(hash, options?)` 财务报告和审定财务报表 `getMany(hashes, options?)`。 。 。 . 它没有象征性供应商、头钩、上市或变异方法。 请求 省略环境证书并拒绝重定向。 配置接受绝对 HTTP( S) URL, 包括共享主机路径前缀, 并拒绝用户信息 碎片 明确允许当地HTTP;地址/DNS政策仍然是: 主人的责任。 可选 `fetchImpl` 是一个可信任的传输覆盖 这必须保留这些政策。 如果没有它,则按要求的时间解决取回问题.

`maxResponseBytes` 是一个可选的正安全整数。 它计算解码后抓取 jSON 解析前的响应-流字节,关于成功和错误反应, 包括整个本地对象/阵列及其元数据。 排除意味着没有大小 限制。 它不约束原始压缩流量、头条、减压工作或 连接缓冲器。 该信号被传送到获取中,并在 身体消耗; 中止不会无限期地等待流清理.

成功读取验证存储的负载形状并保存所有字段 . 既不要求路径,也不要求路径 `_hash`编号 :`_dataHash` 元数据核实内容身份; 需要内容保证的呼叫者必须散开并验证返回的数据. 运输、规模、取消、反应不善和准入失败依然存在 未读取, 而不是证明广告对象从未存在 .

公众浏览器访问适用于 **整个数据湖**,包括提供者方 盘点和使用API. 更喜欢专用的公共取景湖 经认证的作家;公共跑道访问也允许突变。 新湖泊 和浏览器访问额外要求 提供者的 CORS 配置 。 该客户端不会改变ACL或保留.

公共读者要求释放 `@ariestools/sdk` 8.2.0或相容性 8.2补丁,加所需补丁 `@opentelemetry/api` 鼠标。 这不需要Zod 用于这些读取;其他 SDK 特性和 Datalake 等同器可以有单独的需要.

## 常见问题

### @ariestools/aries-datalake-client 是什么？

Aries 点播 XL1 数据湖控制平面的客户端 SDK

### 如何安装 @ariestools/aries-datalake-client？

在项目目录运行 npm install @ariestools/aries-datalake-client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@opentelemetry/api（^1\.10）、@ariestools/cli-kit-daemon（^2\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ariestools/aries-datalake-client 支持 TypeScript 吗？

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

### @ariestools/aries-datalake-client 支持 ESM 还是 CommonJS？

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

### @ariestools/aries-datalake-client 需要什么版本的 Node\.js？

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

### @ariestools/aries-datalake-client 可以商用吗？

@ariestools/aries-datalake-client 使用 LGPL-3\.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @ariestools/aries-datalake-client 的下载量有多少？

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

### @ariestools/aries-datalake-client 还在维护吗？

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