概述 - Meilisearch 文档 - Meilisearch 搜索引擎

本参考文档描述了 Meilisearch RESTful API 的通用行为。如果您是 Meilisearch 新手，请查看入门指南。

OpenAPI

Meilisearch OpenAPI 规范 (meilisearch-openapi.json) 附在 Meilisearch 最新版本中

文档约定

本 API 文档使用以下约定

API 路由中的大括号 ({}) 表示路径参数，例如，GET /indexes/{index_uid}
必填字段标有星号 (*)
占位符文本为大写字符并带有下划线分隔符，例如，MASTER_KEY

授权

通过在启动时为 Meilisearch 提供主密钥，您可以保护实例免受未经授权的请求。提供的主密钥必须至少为 16 字节。从那时起，您必须包含 Authorization 请求头和有效的 API 密钥才能访问受保护的路由（除了 /health 之外的所有路由）。

# replace the MASTER_KEY placeholder with your master key
curl \
  -X GET 'MEILISEARCH_URL/keys' \
  -H 'Authorization: Bearer MASTER_KEY'

/keys 路由只能使用主密钥访问。出于安全考虑，我们建议所有其他路由都使用常规 API 密钥。

v0.24 及以下版本使用 X-MEILI-API-KEY: apiKey 授权请求头

curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'X-Meili-API-Key: API_KEY'

要了解更多关于密钥和安全的信息，请参阅我们的安全教程。

分页

Meilisearch 会对所有返回多个资源的 GET 路由进行分页，例如 GET /indexes、GET /documents、GET /keys 等。这使您可以处理可管理的数据块。所有这些路由每页返回 20 个结果，但您可以使用 limit 查询参数进行配置。您可以使用 offset 在页面之间移动。所有分页响应都包含以下字段：

名称	类型	描述
`偏移量`	整数	跳过的资源数量
`限制`	整数	返回的资源数量
`总数`	整数	资源总数

`/tasks` 端点

由于 /tasks 端点使用不同类型的分页，因此响应包含不同的字段。您可以在任务 API 参考中阅读更多相关信息。

参数

参数是您可以传递给 API 端点以修改其响应的选项。Meilisearch API 中有三种主要类型的参数：请求体参数、路径参数和查询参数。

请求体参数

这些参数是 POST、PUT 和 PATCH 请求的强制组成部分。它们根据您正在修改的资源接受各种值和数据类型。您必须将这些参数添加到请求的数据负载中。

路径参数

这些参数是您在端点路径中传递给 API 的参数。它们用于唯一标识资源。您可以有多个路径参数，例如 /indexes/{index_uid}/documents/{document_id}。如果端点不接受任何路径参数，则该端点的文档中不包含此部分。

查询参数

这些可选参数是键值对序列，出现在端点中的问号 (?) 之后。您可以通过用和号 (&) 分隔来列出多个查询参数。查询参数的顺序无关紧要。它们主要用于 GET 端点。如果端点不接受任何查询参数，则该端点的文档中不包含此部分。

请求头

内容类型

任何带有有效载荷 (--data-binary) 的 API 请求都需要一个 Content-Type 请求头。内容类型请求头指示资源的媒体类型，帮助客户端正确处理响应体。 Meilisearch 目前支持以下格式：

JSON 的 Content-Type: application/json
NDJSON 的 Content-Type: application/x-ndjson
CSV 的 Content-Type: text/csv

只有添加文档和更新文档端点接受 NDJSON 和 CSV。对于所有其他端点，请使用 Content-Type: application/json。

内容编码

Content-Encoding 请求头指示媒体类型是否通过给定算法进行压缩。压缩通过发送和接收较小的有效载荷来提高传输速度并减少带宽消耗。相反，Accept-Encoding 请求头指示客户端理解的压缩算法。 Meilisearch 支持以下压缩方法：

br：使用 Brotli 算法
deflate：使用 zlib 结构和 deflate 压缩算法
gzip：使用 gzip 算法

请求压缩

以下代码示例使用 Content-Encoding: gzip 请求头，表示请求体使用 gzip 算法压缩

 cat ~/movies.json | gzip | curl -X POST 'MEILISEARCH_URL/indexes/movies/documents' --data-binary @- -H 'Content-Type: application/json' -H 'Content-Encoding: gzip'

响应压缩

如果请求包含 Accept-Encoding 请求头，Meilisearch 将压缩响应。以下代码示例使用 gzip 算法

curl -sH 'Accept-encoding: gzip' 'MEILISEARCH_URL/indexes/movies/search' | gzip -

请求体

请求体是发送到 API 的数据。它与 PUT、POST 和 PATCH 方法一起使用，用于创建或更新资源。您必须以 JSON 格式提供请求体。

响应体

Meilisearch 是一个异步 API。这意味着在响应大多数写入请求时，您将收到一个简要的 task 对象版本

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "indexUpdate",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

您可以使用此 taskUid 获取有关任务状态的更多详细信息。查看更多关于异步操作的信息。

数据类型

Meilisearch API 支持 JSON 数据类型。

API 参考

错误

​OpenAPI

​文档约定

​授权

​分页

​/tasks 端点

​参数

​请求体参数

​路径参数

​查询参数

​请求头

​内容类型

​内容编码

​请求压缩

​响应压缩

​请求体

​响应体

​数据类型

OpenAPI

文档约定

授权

分页

`/tasks` 端点

参数

请求体参数

路径参数

查询参数

请求头

内容类型

内容编码

请求压缩

响应压缩

请求体

响应体

数据类型