Meilisearch 中文文档

/keys 路由允许您创建、管理和删除 API 密钥。要使用这些端点，您必须首先设置主密钥。一旦设置了主密钥，您可以通过在请求头中提供它，或使用具有 keys.get、keys.create、keys.update 或 keys.delete 操作权限的 API 密钥来访问这些端点。

在没有设置主密钥的情况下访问 /keys 路由会抛出 missing_master_key 错误。

密钥对象

{
  "name": "默认搜索 API 密钥",
  "description": "用于从前端代码进行搜索",
  "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99",
  "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37",
  "actions": [
    "search"
  ],
  "indexes": [
    "*"
  ],
  "expiresAt": null,
  "createdAt": "2021-08-11T10:00:00Z",
  "updatedAt": "2021-08-11T10:00:00Z"
}

`name`

类型: 字符串

默认值: null

描述: 密钥的可读名称

`description`

类型: 字符串

默认值: null

描述: 密钥的描述。您可以在此添加关于密钥的任何重要信息

`uid`

类型: 字符串

默认值: 不适用

描述: 用于标识 API 密钥的 uuid v4。如果未指定，Meilisearch 会自动生成

`key`

类型: 字符串

默认值: 不适用

描述：由 Meilisearch 通过哈希处理 uid 和主密钥生成的字母数字键值，用于 API 密钥创建时。在向受保护的 Meilisearch 实例发起调用时用于授权认证。

该值也用作路径变量 {key} 来更新、删除或获取特定密钥。

如果主密钥变更，所有 key 值将自动变更。

自定义 API 密钥具有确定性：key 是 uid 和主密钥的 SHA256 哈希值。要复用自定义 API 密钥，需使用相同主密钥启动新实例，并以相同 uid 重新创建 API 密钥。

默认 API 密钥无法跨实例复用。Meilisearch 会在首次启动实例时自动生成其 uid。

`actions`

类型：数组

默认值：不适用

描述: 一个表示该密钥允许执行的 API 操作的字符串数组。API 操作只能在授权的 indexes 上执行。使用 ["*"] 表示允许所有操作。

您可以使用 * 作为通配符来访问 documents、indexes、tasks、settings、stats 和 dumps 操作的所有端点。例如，documents.* 授予所有文档操作的访问权限。

出于安全考虑，我们不建议创建可以执行所有操作的密钥。

名称	描述
`search`	提供对 `POST` 和 `GET` 搜索端点的访问权限
`documents.add`	提供对添加文档和更新文档端点的访问权限
`documents.get`	提供对获取单个文档、使用 POST 获取文档和使用 GET 获取文档端点的访问权限
`documents.delete`	提供对删除单个文档、删除所有文档、批量删除和按条件删除端点的访问权限
`indexes.create`	提供对创建索引端点的访问权限
`indexes.get`	提供对获取单个索引和列出所有索引端点的访问权限。未授权的 `indexes` 将从响应中省略
`indexes.update`	提供对更新索引端点的访问权限
`indexes.delete`	提供对删除索引端点的访问权限
`indexes.swap`	提供对交换索引端点的访问权限。未授权的 `indexes` 不会被交换
`tasks.get`	提供对获取单个任务和获取任务列表端点的访问权限。来自未授权 `indexes` 的任务将从响应中省略
`tasks.cancel`	提供对取消任务端点的访问权限。来自未授权 `indexes` 的任务不会被取消
`tasks.delete`	提供对删除任务端点的访问权限。来自未授权 `indexes` 的任务不会被删除
`settings.get`	提供对获取设置端点及其所有子路由等效端点的访问权限
`settings.update`	提供对更新设置和重置设置端点及其所有子路由等效端点的访问权限
`stats.get`	提供对获取索引统计信息和获取所有索引统计信息端点的访问权限。对于后者，未授权的 `indexes` 将从响应中省略
`dumps.create`	提供对创建转储文件端点的访问权限。不受 `indexes` 限制
`snapshots.create`	提供对创建快照端点的访问权限。不受 `indexes` 限制
`version`	提供对获取 Meilisearch 版本端点的访问权限
`keys.get`	提供对获取所有密钥端点的访问权限
`keys.create`	提供对创建密钥端点的访问权限
`keys.update`	提供对更新密钥端点的访问权限
`keys.delete`	提供对删除密钥端点的访问权限
`network.get`	提供对获取网络对象端点的访问权限
`network.update`	提供对更新网络对象端点的访问权限

`indexes`（索引）

类型: 数组

默认值: 无

描述: 该 API 密钥被授权操作的索引数组。使用 ["*"] 表示所有索引。密钥只能在指定的索引上执行其允许的操作。

你也可以在字符串末尾使用 * 通配符，这将允许 API 密钥访问所有以该字符串开头的索引。例如，使用 "indexes": ["movie*"] 将允许 API 密钥访问 movies 和 movie_ratings 索引。

`expiresAt`（过期时间）

类型: 字符串

默认值: 无

描述: 密钥的过期日期和时间，使用 RFC 3339 格式表示。如果密钥永不过期则为 null

一旦密钥超过 expiresAt 指定的日期，使用该密钥进行 API 授权将返回错误。

`createdAt`（创建时间）

类型: 字符串

默认值: null

描述: 密钥的创建日期和时间，使用 RFC 3339 格式表示

`updatedAt`（更新时间）

类型: 字符串

默认值: null

描述: 密钥最后更新的日期和时间，使用 RFC 3339 格式表示

获取所有密钥

GET

/keys

返回最近创建的 20 个密钥，结果存储在 results 数组中。响应中包含已过期的密钥，但不包含已删除的密钥。

查询参数

可以使用 offset 和 limit 查询参数对结果进行分页。

查询参数	默认值	描述
`offset`	`0`	跳过的密钥数量
`limit`	`20`	返回的密钥数量

响应

名称	类型	描述
`results`	数组	包含密钥对象的数组
`offset`	整数	跳过的密钥数量
`limit`	整数	返回的密钥数量
`total`	整数	API密钥的总数

示例

curl \
  -X GET 'MEILISEARCH_URL/keys?limit=3' \
  -H 'Authorization: Bearer MASTER_KEY'

响应: `200 Ok`

{
  "results": [
    {
      "name": null,
      "description": "管理文档: 产品/评论API密钥",
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
      "actions": [
        "documents.add",
        "documents.delete"
      ],
      "indexes": [
        "prod*",
        "reviews"
      ],
      "expiresAt": "2021-12-31T23:59:59Z",
      "createdAt": "2021-10-12T00:00:00Z",
      "updatedAt": "2021-10-13T15:00:00Z"
    },
    {
      "name": "默认搜索API密钥",
      "description": "用于前端代码执行搜索",
      "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99",
      "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37",
      "actions": [
        "search"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    },
    {
      "name": "默认管理员API密钥",
      "description": "用于非搜索操作。注意！不要在前端公开暴露此密钥",
      "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f",
      "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213",
      "actions": [
        "*"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    }
  ],
  "offset": 0,
  "limit": 3,
  "total": 7
}

API密钥按其createdAt日期降序排列显示。这意味着最近创建的密钥会优先显示。

获取单个密钥

GET

/keys/{key_or_uid}

获取指定密钥的信息。尝试使用此端点查询不存在或已删除的密钥会导致错误。

路径参数

需要提供有效的 API key 或 uid。

名称	类型	描述
`key` *	字符串	请求的 API key 的 `key` 值
`uid` *	字符串	请求的 API key 的 `uid` 标识

示例

curl \
  -X GET 'MEILISEARCH_URL/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

响应: `200 Ok`

{
  "name": null,
  "description": "添加文档: 产品 API 密钥",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

关于这些字段的解释，请参阅 key 对象。

创建密钥

POST

/keys

根据提供的描述、权限和过期日期创建一个 API 密钥。

请求体

名称	类型	默认值	描述
`actions` *	数组	无	该密钥允许的 API 操作列表。`["*"]` 表示允许所有操作
`indexes` *	数组	无	该密钥有权操作的索引数组。`["*"]` 表示允许所有索引
`expiresAt` *	字符串	无	密钥过期日期和时间，使用 RFC 3339 格式表示。`null` 表示密钥永不过期
`name`	字符串	`null`	密钥的可读名称
`uid`	字符串	无	用于标识 API 密钥的 uuid v4。如果未指定，将由 Meilisearch 自动生成
`description`	字符串	`null`	密钥的可选描述信息

示例

curl \
  -X POST 'MEILISEARCH_URL/keys' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "添加文档：产品API密钥",
    "actions": ["documents.add"],
    "indexes": ["products"],
    "expiresAt": "2042-04-02T00:42:42Z"
  }'

响应: `201 Created`

{
  "name": null,
  "description": "管理文档: 产品/评论API密钥",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

更新密钥

PATCH

/keys/{key_or_uid}

更新API密钥的name和description字段。

密钥更新是部分更新。这意味着您只需要提供想要更新的字段，未包含在请求体中的字段将保持不变。

路径参数

需要提供有效的API key或uid。

名称	类型	描述
`key` *	字符串	请求API密钥的`key`值
`uid` *	字符串	请求API密钥的`uid`标识符

请求体

名称	类型	默认值	描述
`name`	字符串	`null`	密钥的人类可读名称
`description`	字符串	`null`	密钥的可选描述信息

示例

curl \
  -X PATCH 'MEILISEARCH_URL/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "name": "Products/Reviews API key",
    "description": "Manage documents: Products/Reviews API key"
  }'

响应: `200 成功`

{
  "name": "产品/评价API密钥",
  "description": "管理文档: 产品/评价API密钥",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add",
    "documents.delete"
  ],
  "indexes": [
    "products",
    "reviews"
  ],
  "expiresAt": "2021-12-31T23:59:59Z",
  "createdAt": "2021-10-12T00:00:00Z",
  "updatedAt": "2021-10-13T15:00:00Z"
}

删除密钥

DELETE

/keys/{key_or_uid}

删除指定的API密钥。

路径参数

需要提供有效的API key 或 uid。

名称	类型	描述
`key` *	字符串	请求API密钥的`key`值
`uid` *	字符串	请求API密钥的`uid`标识符

示例

curl \
  -X DELETE 'MEILISEARCH_URL/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

API 参考

错误

密钥管理

密钥对象

`name`

`description`

`uid`

`key`

`actions`

`indexes`（索引）

`expiresAt`（过期时间）

`createdAt`（创建时间）

`updatedAt`（更新时间）

获取所有密钥

查询参数

响应

示例

响应: `200 Ok`

获取单个密钥

路径参数

示例

响应: `200 Ok`

创建密钥

请求体

示例

响应: `201 Created`

更新密钥

路径参数

请求体

示例

响应: `200 成功`

删除密钥

路径参数

示例

响应: `204 无内容`

API 参考

错误

​密钥对象

​name

​description

​uid

​key

​actions

​indexes（索引）

​expiresAt（过期时间）

​createdAt（创建时间）

​updatedAt（更新时间）

​获取所有密钥

​查询参数

​响应

​示例

​响应: 200 Ok

​获取单个密钥

​路径参数

​示例

​响应: 200 Ok

​创建密钥

​请求体

​示例

​响应: 201 Created

​更新密钥

​路径参数

​请求体

​示例

​响应: 200 成功

​删除密钥

​路径参数

​示例

​响应: 204 无内容

密钥对象

`name`

`description`

`uid`

`key`

`actions`

`indexes`（索引）

`expiresAt`（过期时间）

`createdAt`（创建时间）

`updatedAt`（更新时间）

获取所有密钥

查询参数

响应

示例

响应: `200 Ok`

获取单个密钥

路径参数

示例

响应: `200 Ok`

创建密钥

请求体

示例

响应: `201 Created`

更新密钥

路径参数

请求体

示例

响应: `200 成功`

删除密钥

路径参数

示例

响应: `204 无内容`