# @elastic\.io/maester-client 中文文档

规范地址：https://npmcn.com/package/%40elastic.io/maester-client/

版本：6\.0\.3
npm 元数据更新时间：2026-08-27T08:52:47.323Z
中文译文更新时间：2026-11-13T10:46:13.857Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：314 kB，58 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：24\.x
- 运行依赖：5 个
- 首次发布：2020-04-17T08:55:02.371Z
- 最新版本发布：2026-08-27T08:52:47.167Z
- 近 30 天下载量：15330（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 10 个）

## 中文简介

官方对象存储客户端

## 安装

```sh
npm install @elastic.io/maester-client
```

也可以使用：`pnpm add @elastic.io/maester-client`、`yarn add @elastic.io/maester-client`、`bun add @elastic.io/maester-client`

## README

# 学士客户端

官方 Elastic.io 对象存储客户端.

## 使用量

这个图书馆向你们推荐两个客户: `ObjectStorage` 打开 `ObjectStorageWrapper`。 。 。 . 使用 `ObjectStorageWrapper` 以数据操作 `string`, (中文(简体) ), `number`, (中文(简体) ), `object`, (中文(简体) ), `array` 使用 `ObjectStorage` 用于操作附件(也可用于与 `ObjectStorageWrapper`(中文(简体) )

注意: 所有代码片段用 Typescript 写

### 环境变量

_请求( MA)_ - 指定在服务器或连接出错时尝试重试失败请求的次数.  
默认值:3. 最小值:0. 最大值: 4. 如果配置的值超出限制,则会使用默认值.

_请求不适用_ - 在请求时间到期前指定持续时间以毫秒为单位。 如果请求超过这一期限,则中止.  
默认值: 15000(15秒). 最小值:500(0.5秒). 最大值: 120000 (20分). 如果配置的值超出限制,则会使用默认值.

### 创建客户端

```
import { ObjectStorage, ObjectStorageWrapper } from '@elastic.io/maester-client';

const objectStorageWrapper = new ObjectStorageWrapper(this);
const objectStorage = new ObjectStorage(creds);
```

## 对象StorageWrapper CRUD 操作

### 创建对象

该方法的签名如下:

```
async createObject(data: object, queryHeaders?: Header[], metaHeaders?: Header[], ttl?: number)
```

地点

-   数据 - 要创建的任何数据. _需求_
-   查询标题 - 对象数组 `{ key: string, value: string }`,当前最大值 - 5项。 何处 `key` (必须是小写) - 可搜索的字段名(见下文 `Get objects by query parameters` 如果指定,则整个阵列必须具有独有性 `value` 还必须具体说明; `value` - 可搜索的字段值,如果指定 -- `key` 还必须具体说明. _可选_
-   元页眉 - 对象数组 `{ key: string, value: string }`时 `key` (必须是小写) - 元字段名,必须对整个数组独有,如果指定的话 - `value` 还必须具体说明; `value` - 元字段值,如果指定 -- `key` 还必须具体说明. _可选_
-   ttl - 可配置对象活活的时间,秒. _可选_

```
const obj = await objectStorageWrapper.createObject(data);
const obj = await objectStorageWrapper.createObject(data, [], [], 100000);
const obj = await objectStorageWrapper.createObject(
  data,
  [{key: 'somequeriablefieldkey', value: 'somequeriablefieldvalue'}],
  [{key: 'somemetakey', value: 'somemetavalue'}],
  60000
);
const obj = await objectStorageWrapper.createObject(
  data,
  [{key: 'anotherqueriablefieldkey', value: 'anotherqueriablefieldvalue'}, {key: 'anotherqueriablefieldkey2', value: 'anotherqueriablefieldvalue2'}],
  [{key: 'somemetakey', value: 'somemetavalue'}],
  60000
);
```

### 读取操作

#### 通过 ID 获取对象

返回 JSON 对象。 该方法的签名如下:

```
async lookupObjectById(id: string)
```

地点

-   id - 天体内部的学士ID来查看. 例如"76380cae-aee3-457a-9029-d971f61e3731". _需求_

```
const obj = await objectStorageWrapper.lookupObjectById(id);
```

#### 通过查询参数获取对象

该方法的签名如下:

```
async lookupObjectsByQueryParameters(headers: Header[])
```

地点

-   页眉 - 对象数组 `{ key: string, value: string }`,当前最大值 - 5项。 何处 `key` (必须是小写) - 可搜索的字段名,必须对整个数组独有,如果指定的话 - `value` 还必须具体说明; `value` - 可搜索的字段值,如果指定 -- `key` 还必须具体说明. _需求_

如果您创建了一个带有可填充头的对象, 内部看起来是这样的:

```
x-query-somequeriablefieldkey: somequeriablefieldvalue
x-query-anotherqueriablefieldkey: anotherqueriablefieldvalue
```

其中"x-query-"是一个默认的前缀.

使用 REST API 学士,您可以通过 :

```
/objects?query[somequeriablefieldkey]=somequeriablefieldvalue&query[anotherqueriablefieldkey]=anotherqueriablefieldvalue
```

使用图书馆:

```
const objects = await objectStorageWrapper.lookupObjectsByQueryParameters([
  { key: 'somequeriablefieldkey', value: 'somequeriablefieldvalue' },
  { key: 'anotherqueriablefieldkey', value: 'anotherqueriablefieldvalue' }
]);
```

方法返回一系列项目。 如果找不到对象或包含对象, 它要么是空的

### 更新对象

该方法的签名如下:

```
async updateObject(id: string, data: object, queryHeaders?: Header[], metaHeaders?: Header[])
```

地点

-   id - 天体的内部ID学士来更新. 例如"76380cae-aee3-457a-9029-d971f61e3731". _需求_
-   数据 - 要更新的对象. _需求_
-   查询标题 - 对象数组 `{ key: string, value: string }`,当前最大值 - 5项。 何处 `key` (必须是小写) - 可搜索的字段名(见下文 `Get objects by query parameters` 如果指定,则整个阵列必须具有独有性 `value` 还必须具体说明; `value` - 可搜索的字段值,如果指定 -- `key` 还必须具体说明。 注意:查询头可以添加到已存在的对象中,也可以修改,但不能被删除. _可选_
-   元页眉 - 对象数组 `{ key: string, value: string }`时 `key` (必须是小写) - 元字段名,必须对整个数组独有,如果指定的话 - `value` 还必须具体说明; `value` - 元字段值,如果指定 -- `key` 还必须具体说明。 注:元头可以添加到已存在的对象中,也可以被修改,但不能被删除. _可选_

```
const obj = await objectStorageWrapper.updateObject(id, data);
const obj = await objectStorageWrapper.updateObject(
  id,
  data,
  [{ key: 'somequeriablefieldkey', value: 'somequeriablefieldvalue' }, { key: 'anotherqueriablefieldkey', value: 'anotherqueriablefieldvalue' }]
);
const obj = await objectStorageWrapper.updateObject(
  id,
  data,
  [{key: 'anotherqueriablefieldkey', value: 'anotherqueriablefieldvalue'}, {key: 'anotherqueriablefieldkey2', value: 'anotherqueriablefieldvalue2'}],
  [{key: 'somemetakey', value: 'somemetavalue'}]
);
```

### 删除操作

#### 用 ID 删除对象

该方法的签名如下:

```
async deleteObjectById(id: string)
```

地点

-   id - 要删除的对象的学士内部id. 例如"76380cae-aee3-457a-9029-d971f61e3731". _需求_

```
const obj = await objectStorageWrapper.deleteObjectById(id);
```

#### 通过查询参数删除对象

该方法的签名如下:

```
async deleteObjectsByQueryParameters(headers: Header[])
```

地点

-   页眉 - 对象数组 `{ key: string, value: string }`,当前最大值 - 5项。 何处 `key` (必须是小写) - 可搜索的字段名,必须对整个数组独有,如果指定的话 - `value` 还必须具体说明; `value` - 可搜索的字段值,如果指定 -- `key` 还必须具体说明. _需求_

```
const obj = await objectStorageWrapper.deleteObjectsByQueryParameters([{key: 'somequeriablefieldkey', value: 'somequeriablefieldvalue'}]);
```

## 对象Storage CRUD 操作

### 创建对象

该方法的签名如下:

```
async add(dataOrFunc: uploadData | (() => Promise<Readable>), reqWithBodyOptions?: ReqWithBodyOptions)
```

地点

-   数据OrFunc - async函数返回流或任何数据(除"未定义").
-   [req with Body 选项](https://npmcn.com/src/interfaces.ts#L27)。 。 。 .

```
const obj = await objectStorage.add(data, { headers: {'x-query-somequeriablefieldkey': 'somequeriablefieldvalue'} });
const getAttachAsStream = async () => (await axios.get('https://img.jpg', { responseType: 'stream' })).data;
const obj = await objectStorage.add(getAttachAsStream, { retryOptions: { retriesCount: 5, requestTimeout: 60000 } });
);
```

### 读取操作

#### 通过 ID 获取对象

该方法的签名如下:

```
async getOne(objectId: string, reqOptions: ReqOptions = {})
```

地点

-   id - 天体内部的学士ID来查看. 例如"76380cae-aee3-457a-9029-d971f61e3731".
-   [req 选项](https://npmcn.com/src/interfaces.ts#L22)。 。 。 .

```
const { data, headers } = await objectStorage.getOne(id);
const { data: stream, headers } = await objectStorage.getOne(id, { responseType: 'stream'});
```

#### 通过查询参数获取对象

该方法的签名如下:

```
async getAllByParams(params: object, reqOptions: ReqOptions = {})
```

地点

-   params - 查询参数的对象,当前最大值 - 5项.
-   [req 选项](https://npmcn.com/src/interfaces.ts#L22)。 。 。 .

实例:

```
const obj = await objectStorage.getAllByParams({ 'query[field]': 'value' });
```

方法返回一系列项目。 如果找不到对象或包含对象, 它要么是空的

### 更新对象

该方法的签名如下:

```
async update(objectId: string, dataOrFunc: uploadData | (() => Promise<Readable>), reqWithBodyOptions?: ReqWithBodyOptions)
```

地点

-   objectId - 要更新的对象的ID.
-   数据OrFunc - async函数返回流或任何数据(除"未定义").
-   [req with Body 选项](https://npmcn.com/src/interfaces.ts#L27)

```
const obj = await objectStorage.update(data, { headers: {'x-query-somequeriablefieldkey': 'somequeriablefieldvalue'} });
const getAttachAsStream = async () => (await axios.get('https://img.jpg', { responseType: 'stream' })).data;
const obj = await objectStorage.update(getAttachAsStream);
);
```

### 删除操作

#### 用 ID 删除对象

该方法的签名如下:

```
async deleteOne(objectId: string, reqOptions: ReqOptions = {})
```

地点

-   id - 要删除的对象的学士内部id. 例如"76380cae-aee3-457a-9029-d971f61e3731".
-   [req 选项](https://npmcn.com/src/interfaces.ts#L22)。 。 。 .

```
const obj = await objectStorage.deleteOne(id);
const obj = await objectStorage.deleteOne(id, { retryOptions: { retriesCount: 5, requestTimeout: 60000 } });
```

#### 通过查询参数删除对象

该方法的签名如下:

```
async deleteAllByParams(params: object, reqOptions: ReqOptions = {})
```

地点

-   params - 查询参数的对象,当前最大值 - 5项.
-   [req 选项](https://npmcn.com/src/interfaces.ts#L22)。 。 。 .

```
const obj = await objectStorage.deleteAllByParams({ 'query[field]': 'value' });
```

### 其他方法

#### 使用方法

该方法的签名如下:

```
async use(forward: TransformMiddleware, reverse: TransformMiddleware)
```

地点

-   前进 - 转换要使用的中间软件 `Create` 财务报告和审定财务报表 `Update` 对象操作( e)`add`, (中文(简体) ), `update` 方法问题.
-   倒转 - 将中间软件转换为 `Get` 对象操作( e)`getOne`, (中文(简体) ), `getAllByParams` 方法问题.

#### 获取页眉方法

该方法的签名如下:

```
async getHeaders(objectId: string, reqOptions: ReqOptions = {})
```

地点

-   前进 - 转换要使用的中间软件 `Create` 财务报告和审定财务报表 `Update` 对象操作( e)`add`, (中文(简体) ), `update` 方法问题.
-   倒转 - 将中间软件转换为 `Get` 对象操作( e)`getOne`, (中文(简体) ), `getAllByParams` 方法问题.

## 处理错误

库所抛出的所有错误都是 `ObjectStorageClientError` 课。 检查导出 `Errors` a 财产 列出所有错误类别及其属性.

## 限制

1.  两者 `ObjectStorage` 财务报告和审定财务报表 `ObjectStorageWrapper` 无法处理 `undefined` 作为上调值的值。 还值 `undefined` 将转换为 `null`,例如 `[1, 'str', undefined, null, { d: 2 }]` 将保存为 `[1, 'str', null, null, { d: 2 }]`
2.  一旦对象被创建为自定义的“ 内容类型 ” , 请注意“ 内容类型 ” 可以随此对象的下一次更新请求自动更改 。 为了避免在下次更新请求中再次提供自定义“ 内容类型 ” .  
    例如,如果你创造了这样的反对 `const objectId = await objectStorage.add({ a: 2 }, { headers: { 'content-type': 'some-type' } })` - 对象将用 `'content-type': 'some-type'`。但如果您要更新此对象而不通过相同的自定义“ 内容类型 ” (`await objectStorage.update(objectId, { a: 3 })`) - 对象“ 内容类型” 将自动计算, 在此情况下将设定为“ 应用程序/ json ” .

## 常见问题

### @elastic\.io/maester-client 是什么？

官方对象存储客户端

### 如何安装 @elastic\.io/maester-client？

在项目目录运行 npm install @elastic\.io/maester-client，或使用 pnpm add / yarn add / bun add。

### @elastic\.io/maester-client 支持 TypeScript 吗？

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

### @elastic\.io/maester-client 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @elastic\.io/maester-client 需要什么版本的 Node\.js？

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

### @elastic\.io/maester-client 可以商用吗？

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

### @elastic\.io/maester-client 的下载量有多少？

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

### @elastic\.io/maester-client 还在维护吗？

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