此参考描述了 Meilisearch RESTful API 的通用行为。

如果您是 Meilisearch 的新用户，请查阅入门指南。

​
OpenAPI

您可以在此处获取 Meilisearch OpenAPI 规范。

​
文档约定

此 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 在页面之间移动。

所有分页响应都包含以下字段

名称类型描述
offset整数跳过的资源数量
limit整数返回的资源数量
total整数资源总数

​
/tasks 端点

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

​
参数

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

​
请求正文参数

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

​
路径参数

这些是您在端点路径中传递给 API 的参数。它们用于唯一标识资源。您可以有多个路径参数，例如 /indexes/{index_uid}/documents/{document_id}。

如果端点不接受任何路径参数，则该端点的文档中不会出现此部分。

​
查询参数

这些可选参数是键值对序列，出现在端点中的问号 (?) 之后。您可以通过用和号 (&) 分隔来列出多个查询参数。查询参数的顺序无关紧要。它们主要与 GET 端点一起使用。

如果端点不接受任何查询参数，则该端点的文档中不会出现此部分。

​
标头

​
内容类型

任何带有效负载 (--data-binary) 的 API 请求都需要一个 Content-Type 标头。内容类型标头指示资源的媒体类型，有助于客户端正确处理响应正文。

Meilisearch 目前支持以下格式

  • Content-Type: application/json 用于 JSON
  • Content-Type: application/x-ndjson 用于 NDJSON
  • Content-Type: text/csv 用于 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 数据类型。