@elastic.io/maester-client

中文文档

6.0.3发布于 2026/08/27Apache-2.0TypeScriptCommonJS近 30 天下载 1.5万

官方对象存储客户端

文档目录16 节

使用量
环境变量
创建客户端
对象StorageWrapper CRUD 操作
创建对象
读取操作
更新对象
删除操作
对象Storage CRUD 操作
创建对象
读取操作
更新对象
删除操作
其他方法
处理错误
限制

学士客户端

官方 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 选项。。。 .

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 选项。。。 .

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 选项。。。 .

实例:

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 选项

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 选项。。。 .

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 选项。。。 .

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 财产列出所有错误类别及其属性.

限制

两者 ObjectStorage 财务报告和审定财务报表 ObjectStorageWrapper 无法处理 undefined 作为上调值的值。还值 undefined 将转换为 null,例如 [1, 'str', undefined, null, { d: 2 }] 将保存为 [1, 'str', null, null, { d: 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 共发布 77 个版本，首次发布于 2020/04/17；过去 12 个月发布了 10 个版本。

版本	发布日期	距今
`6.0.3`latest	2026/08/27	2 个月前
`6.0.3-dev.1`dev	2026/08/21	2 个月前
`6.0.2-dev.1`	2026/08/19	2 个月前
`6.0.2`	2026/08/05	3 个月前
`6.0.1`	2026/07/16	3 个月前
`6.0.1-dev.4`	2026/07/10	4 个月前

关于 @elastic.io/maester-client 的常见问题

@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 和提交记录判断。

npm install @elastic.io/maester-client

pnpmpnpm add @elastic.io/maester-client
yarnyarn add @elastic.io/maester-client
bunbun add @elastic.io/maester-client

在你的项目目录中运行此命令。

近 30 天下载

15,330

约 1.5万次日均 511 次

统计周期 2026/10/13 – 2026/11/11
数据来自 npm 官方下载统计，今天更新

最新版本6.0.3发布于 2 个月前

开源许可Apache-2.0宽松许可

包体积314 kB58 个文件 · 解压后

运行依赖5 个

模块格式CommonJS

TypeScript自带类型

Node.js24.x

发布版本77 个近 12 个月 10 个

首次发布2020/04/176 年前

元数据更新2026/08/27

每一个软件包背后，
都有分享与创造的人。