# @cloudbitmaps/azure-blob 中文文档

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

版本：0\.27\.0
npm 元数据更新时间：2026-11-03T05:51:17.516Z
中文译文更新时间：2026-11-10T09:42:29.093Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：188 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：2 个
- 首次发布：2026-09-22T02:44:38.458Z
- 最新版本发布：2026-11-03T05:51:17.135Z
- 近 30 天下载量：1742（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

用于 CloudBitmaps 的 Azure Blob 存储器

## 安装

```sh
npm install @cloudbitmaps/azure-blob
```

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

## README

# @ cloudbitmaps/ azure- bolob (英语)

**Azure Blob 存储用于 [云位图](https://github.com/cloudbitmaps/cloudbitmaps)。 。 。 .** 一个容器 抱着你的世代和他们的指针 所以有 没有第二次服务运行.

> **仅限无害环境管理,节点22.12.** 使用 `import`; 用于 `require()`时标和类型脚本,参见 [常见的JS、快取和类型脚本](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#commonjs-jest-and-typescript)。 。 。 .

> 前1.0:API和上盘格式仍然可以更改. 在npm上,这些文件与它们所运送的版本相符;在GitHub上,它们描述 `main`,更改日志则说每个版本都改变了什么.

## 安装

```bash
pnpm add @cloudbitmaps/roaring @cloudbitmaps/azure-blob
```

安装每张的同版本 `@cloudbitmaps/*` 软件包:它们一起发行,每个包都标出准确的版本 `core` 它是与建造的.

`@azure/storage-blob` (单位:千美元)`^12.23.0`)是这个包的真正依赖性,所以安装是整个步骤. A 类 `containerClient` 您必须来自12.23.0或以后: 驾驶员自己的测试在他们运行在12.0.0, 12.122.0, 12.17.0和 12.18. (没有稳定在12.19至12.22之间): 最老的12.x缺乏驾驶员呼叫的成员,例如 `deleteIfExists`,并在12.18.0上,地下最新的发布,一个读取会将部分路面降低为读取的超时或不会在测试限度内结束,被拒绝的指针读取不会放出其请求. `@cloudbitmaps/core`引擎在下面,随它而来,而你却不给它起名.

## 使用

```ts
import { CloudRoaring } from '@cloudbitmaps/roaring';
import { AzureBlobStorage } from '@cloudbitmaps/azure-blob';

const store = new CloudRoaring({
  storage: new AzureBlobStorage({
    connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
    container: 'bitmaps',
    prefix: 'cr',
  }),
});

await store.load({ segment: 'active-users' }, [1, 2, 3]);
await store.segment('active-users').has(2); // true
```

任何其他密钥都会被姓名拒绝.

| 选项 | 它会做什么 |
| --- | --- |
| `connectionString` 财务报告和审定财务报表 `container` | 为您建立容器客户端 |
| `containerClient` | 您自己的容器扫描客户端, 而不是上述两个客户端; 拒绝给予两者 |
| `prefix` | 此商店所写每件事的密钥前缀 |
| `blockBytes` | 所显示的区块大小(默认为8 MiB;上传缓冲一次一个区块并复制到一个机构来进行分级,因此在冲出时最多能保持大约两倍的区块大小,默认情况下为16 MiB,取自驱动程序代码). 超过Azure的4000个米B区块限制 `ValidationError` |
| `maxObjectBytes` | 最大块( 默认) `blockBytes` ×50,000,约390 GiB). 50 000个4 000个米B以上的区块,大约190.7个TiB,是一种 `ValidationError` |
| `readTimeoutMs` | 每一个读取请求可能需要多长时间, 包括它的身体, 在它被切除之前 `TransientError` 商店的读取重试重复( 默认) `0`关闭) |
| `conditionalDelete` | 服务是否适用 `ifMatch` 在“删除 Blob” 上: 登记簿将删除一行被删除, 而不是留下墓碑, 每一份完整的列表都读取, 而存储的一半只删除了“ 擦除” 的持有人, 而“ 擦除” 则读取“ 擦除” 。 默认情况下: Azure Blob 适用先决条件,而Azulite 也适用先决条件. 有快照的blob拒绝删除(`409 SnapshotsPresent`),而扫荡则算入其中 `purgeFaults`。需要一个可以删除登记册前缀上blobs的角色 |

## 生产前

-   **此后端位于已验证的信封外.** 它通过与S3相同的套房,但证明 缩放和校正在S3上完成。 你是一个早期用户.
-   **运行 `await store.preflight()` 第一次载货之前.** 它会写、试图再写、读、列出和删除一个探测器 浏览登记簿和答案 `{ ok, checks }`它的生命周期检查总是 `unchecked` 这里(见下文),所以跑步还需要手边检查规则。 这个 不检查删除或版本后的读取, 除其他外: [完整列表](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#what-preflight-does-not-check)。 。 。 .
-   **授予容器的数据权限.** 图书馆写块, 承诺块列表, 读取blobs及其 属性、列表和删除. `Storage Blob Data Contributor` 在容器上覆盖他们全部。 连接 字符串带有账户密钥, 账户密钥的授予要多得多 : `containerClient` 由管理下的身份构建.
-   **写入保证 骑着blob ETags和 `If-None-Match: *`**,所以没有其他 需要启动.
-   **切勿添加寿命周期规则, 以终止当前 blobs 或 `registry/` 前缀.**
-   **`await backend.checkLifecycle()` 总是 `unchecked` 在这里.** 寿命周期管理政策属于存储 ,在管理平面上,blob客户端无法读取,而本软件包不需管理依赖. 内容 `detail` 给 `az storage account management-policy show` 命令和寻找什么,包括一条没有的规则 `prefixMatch` (单位:千美元)[从代码中检查生命周期规则](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#check-the-lifecycle-rules-from-code)) (中文(简体) ).
-   **写作的瞬间失败 `TransientError`,而写作可能已经着陆,也可能没有着陆.** 重开电话, 或检查 `store.generations(ref)`。每个书写都会被随机的ID标记,在冲突时,会读取存储的blob 背面:一个携带写作本身的id是成功的,其他的都是 `WriteConflictError`。登记行 复读并不确定,因为一个作家在复读之前, 将一个落地的字写成 上报冲突,所以登记簿将一行中的每个冲突都扔出为 `unsettledConflict`。一个负载的发布 重新读取行,并且只在指针仍然为它的一代和行命名时找到其写作 `pointerId` 是它自己写的;被新的负载所取代,它报告 `superseded`,以及 `segment.load-refused` 事件携带 `unanswered: true`,就像一个没有答案的写完之后。 输掉普通赛车的负载被拒绝也一样 注册,因为驱动程序无法看到客户端的重试 。 翻来翻去再读一遍,直到 指针正对着它的目标 在它发出的信号上 标记存在是因为客户端自己的重试没有按要求进行 开关。 重试后又发来一封信 `503 ServerBusy` 或一个 `500 OperationTimedOut`。其行写入的负载 没有答案读行 并发送一个新的比较和抽取 从它,最多三次, 而政策运行 每一个下方:一个从未回答的注册,在投出负载之前,花费高达保险单尝试的四倍 `TransientError` 并保留其对象: 在 SDK 的默认时间表下, 每笔约 16 s (它等待 0, 4 s, 然后是 12 s) 因此,大约64 s为四人写作, 加上高达3.5 s的出版社自己的等待(来源于此) 时间表,未计量)。 一个保留扫描 `tombstoneGraceMs` 必须在窗口上方;默认为24小时.
-   **设定 `readTimeoutMs` 绑住一个书摊.** 没有客户端设置 : SDK 的每行计时器一旦停止 反应头已经到来,所以只要连接保持畅通 就会被拖住 与 `readTimeoutMs` 设定,每个读取请求(读取范围、尾读属性及其下载、注册行) 读取),未完成,包括正文,其中许多毫秒被中止并投掷 `TransientError`,该 商店的读取重试运行。 它关闭,除非你启动它。 钟从呼叫开始进入SDK,所以等待 用于套接字或证书的值。 书写,删除和列表不计时.
-   **驾驶员在丢弃前会校正其识别出的错误的证书 .** SDK保持签名请求 `err.request` 财务报告和审定财务报表 `err.response.request`页:1 `Authorization` 页眉 (e)`SharedKey <account>:<signature>`或无记名标志) `sig=` 在它的 URL 中,您管道中的任何标题都会添加(饼干, API 密钥, 客户提供的密钥) 。 它把反应头 和它分析的身体 `err.details`,它不知道的字段没有包含,它使一个机构不解析(一个代理的 HTML 页面) 错误消息的来由,所以一个 403 可以引用所签名的字符串 Azure , 它列出每个 `x-ms-` 带值的页眉, 400 `InvalidHeaderValue` 拒绝的值,以及请求的代理页面或网关正文。 在驱动程序抛出的错误中,证书名称下的值被替换为 `[redacted]` (单位:千美元)`authorization`, (中文(简体) ), `proxy-authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `set-cookie`, (中文(简体) ), `x-api-key`, (中文(简体) ), `x-ms-copy-source-authorization`, (中文(简体) ), `x-ms-encryption-key`, (中文(简体) ), `x-ms-source-encryption-key`, (中文(简体) ), `x-identity-header`, (中文(简体) ), `signature`, (中文(简体) ), `sig`还有SDK的 `encryptionKey`, (中文(简体) ), `accountKey` 和进入标志 `token`在平面标题列表中或地图下的一个,以及记录中一个旁边的值: `...Value` 旁边 `...Name` (阿祖尔的 `HeaderName` 财务报告和审定财务报表 `HeaderValue`页:1 `{ name, value }` 在描述错误的记录中 a `value` 在任何字段的证书名称之外,以及在记录中说明没有出错(没有) `code`, (中文(简体) ), `errorCode` 或者说 `message`),一个头表行中的另一单元格(`{ th, td }`和同样的索引 一个平行列表, 与数字,布尔, `code`, (中文(简体) ), `errorCode` 财务报告和审定财务报表 `message` 留着 在其文本中,这些内容被编辑:一个证书标题行(`Authorization`, (中文(简体) ), `Proxy-Authorization`, (中文(简体) ), `x-ms-copy-source-authorization`一个饼干, `x-api-key`, (中文(简体) ), `x-ms-encryption-key`, (中文(简体) ), `x-ms-source-encryption-key`),在任何行的开头,这就是要签名的字符串如何列出它们 `Authorization` 值、 饼干、 客户提供的密钥、 API 密钥或连接字符串 `AccountKey` 在任何地方名称之后(`name: value`, (中文(简体) ), `name=value`(JSON) (韩语) `SharedKey` 或者说 `Bearer` 任何值; 单自的 JWT( 访问符而无需其计划); SAS `sig=` 值(%-编码、JSON-逃脱或引用); 签名 Azure 引出于一个403个机构(`The MAC signature found in the HTTP request '…'`);和 将证书命名(a)之后的单元格文本 `<th>`编号 :`<td>` 单行, a `<dt>`编号 :`<dd>` 配对, XML `<Name>`编号 :`<Value>`在标题或标题之后)。 引用证书的密钥被编辑为文本 。 无法识别以另一种形式提交的证书( 由列、 以 HTML 实体写成的冒号、 SDK 未解析的单位中以证书命名的元素) `sig` %- 编码了两次, 一个用户和密码写入 URL , 而一个太大, 不适合这些模式的文本被全部替换 。 SDK错误,它载运或显示证书,以及它所达到的每一个错误(它) `cause` 链条, a `AggregateError`是因为 `errors`),被抛出为复制:具有相同原型的原生错误(`instanceof RestError` 握住,留言,堆起, `code`, (中文(简体) ), `statusCode` 财务报告和审定财务报表 `details`,所以分类不变,没有 `request` 财务报告和审定财务报表 `response`,任何函数或存取器属性,非错误的类实例,列表、映射或设置的已命名属性,或超过10个级别的任何事物。 活错误从未被改变,一个只持有纯数据且没有显示证书的错误被抛出.
-   **价钱 `storage.requestsPerSizedRead: 2`。 。 。 .** 读取的指针就是到这里的指针 就像S3和GCS一样 片段的尾部读取是两个请求,它的属性再取其字节,因为Azure Blob没有后缀范围. 下载以属性的 ETag 为条件, 所以是一个 blob 二者之间替换一次,第二个替换是a `TransientError`。设置在您给出的定价配置中 `estimateCost` 或者说 `groundedReport` 从 `@cloudbitmaps/tools`,然后离开 `requestsPerPointerRead` 1时.

这个 [生产清单](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md) 覆盖每个项目, 以及每个后端共享的项目: 客户端上的请求超时, 数据备份和注册, 以及您负载的时间表 .

## 文档

-   [开始](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md)
-   [生产前](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md)
-   [API 参考](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md)
-   [更改日志](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/CHANGELOG.md)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @cloudbitmaps/azure-blob 是什么？

用于 CloudBitmaps 的 Azure Blob 存储器

### 如何安装 @cloudbitmaps/azure-blob？

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

### @cloudbitmaps/azure-blob 支持 TypeScript 吗？

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

### @cloudbitmaps/azure-blob 支持 ESM 还是 CommonJS？

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

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

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

### @cloudbitmaps/azure-blob 可以商用吗？

@cloudbitmaps/azure-blob 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudbitmaps/azure-blob 的下载量有多少？

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

### @cloudbitmaps/azure-blob 还在维护吗？

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