API 参考

本参考文档描述了 Meilisearch RESTful API 的通用行为。

如果您是 Meilisearch 的新手，请查看入门指南。

您可以在此处获取 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 密钥。

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 端点使用不同类型的分页，因此响应包含不同的字段。您可以在任务 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：使用带有 deflate 压缩算法的 zlib 结构
• 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 数据类型。