概述

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

如果你是 Meilisearch 的新用户，请先查看入门指南。

​

OpenAPI

你可以在此获取 Meilisearch OpenAPI 规范文件。

​

文档约定

本 API 文档遵循以下约定：

• API 路由中的花括号({})表示路径参数，例如 GET /indexes/{index_uid}
• 必填字段用星号(*)标记
• 占位文本使用大写字母和下划线分隔符，例如 MASTER_KEY

​

授权认证

通过在启动时为 Meilisearch 提供 master key，你可以保护实例免受未授权请求的影响。提供的 master key 必须至少为 16 字节。之后，访问受保护路由（除 /health 外的所有路由）时必须在 Authorization 头中包含有效的 API key。

# 将 MASTER_KEY 占位符替换为你的主密钥
curl \
  -X GET 'MEILISEARCH_URL/keys' \
  -H 'Authorization: Bearer MASTER_KEY'

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

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}。

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

​

查询参数

这些可选参数以键值对序列的形式出现在端点 URL 的问号 (?) 之后。您可以通过用与号 (&) 分隔来列出多个查询参数。查询参数的顺序无关紧要。它们主要与 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 数据类型。