密钥

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

警告

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

密钥对象

json

{
  "name": "Default Search API Key",
  "description": "Use it to search from the frontend code",
  "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`

类型: 字符串
默认值: N/A
描述: 用于标识 API 密钥的 uuid v4。如果未指定，则由 Meilisearch 自动生成

`key`

类型: 字符串
默认值: N/A
描述: 由 Meilisearch 通过在 API 密钥创建时哈希 uid 和主密钥生成的字母数字密钥值。用于在向受保护的 Meilisearch 实例发出调用时进行授权

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

如果主密钥发生更改，所有 key 值将自动更改。

在实例之间重用 API 密钥

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

您无法在实例之间重用默认 API 密钥。Meilisearch 会在您首次启动实例时自动生成它们的 uid。

`actions`

类型: 数组
默认值: N/A
描述: 密钥允许的 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`	提供对删除密钥端点的访问权限

`indexes`

类型: 数组
默认值: N/A
描述: 密钥授权操作的索引数组。对所有索引使用 ["*"]。只有密钥的允许的操作才能在这些索引上使用。

您还可以使用 * 字符作为通配符，将其添加到字符串的末尾。这允许 API 密钥访问所有以该字符串开头的索引名称。例如，使用 "indexes": ["movie*"] 将授予 API 密钥访问 movies 和 movie_ratings 索引的权限。

`expiresAt`

类型: 字符串
默认值: N/A
描述：密钥过期的日期和时间，以 RFC 3339 格式表示。如果密钥永不过期，则为 null

注意

一旦密钥超过其 expiresAt 日期，使用它进行 API 授权将返回错误。

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

响应

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

示例

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

响应：`200 Ok`

json

{
  "results": [
    {
      "name": null,
      "description": "Manage documents: Products/Reviews API key",
      "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": "Default Search API Key",
      "description": "Use it to search from the frontend code",
      "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": "Default Admin API Key",
      "description": "Use it for anything that is not a search operation. Caution! Do not expose it on a public frontend",
      "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` 值
`uid` *	字符串	请求的 API 密钥的 `uid`

示例

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

响应：`200 Ok`

json

{
  "name": null,
  "description": "Add documents: Products API key",
  "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"
}

有关这些字段的解释，请参阅密钥对象。

创建密钥

POST/keys

使用提供的描述、权限和过期日期创建 API 密钥。

正文

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

示例

curl \
  -X POST 'https://127.0.0.1:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "Add documents: Products API key",
    "actions": ["documents.add"],
    "indexes": ["products"],
    "expiresAt": "2042-04-02T00:42:42Z"
  }'

响应：`201 Created`

json

{
  "name": null,
  "description": "Manage documents: Products/Reviews API key",
  "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。

对密钥的更新是部分的。这意味着您应该只提供您打算更新的字段，因为 payload 中不存在的任何字段都将保持不变。

路径参数

需要有效的 API key 或 uid。

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

正文

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

示例

curl \
  -X PATCH 'https://127.0.0.1:7700/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 Ok`

json

{
  "name": "Products/Reviews API key",
  "description": "Manage documents: Products/Reviews API key",
  "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 'https://127.0.0.1:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

响应：`204 No Content`

编辑此页

这有帮助吗？

想包含更多细节吗？提出问题在我们的公共文档存储库中。

密钥

警告

密钥对象

`name`

`description`

`uid`

`key`

在实例之间重用 API 密钥

`actions`

警告

`indexes`

`expiresAt`

注意

`createdAt`

`updatedAt`

获取所有密钥

查询参数

响应

示例

响应：`200 Ok`

注意

获取一个密钥

路径参数

示例

响应：`200 Ok`

创建密钥

正文

示例

响应：`201 Created`

更新密钥

路径参数

正文

示例

响应：`200 Ok`

删除密钥

路径参数

示例

响应：`204 No Content`

这有帮助吗？

密钥

警告

密钥对象

name

description

uid

key

在实例之间重用 API 密钥

actions

警告

indexes

expiresAt

注意

createdAt

updatedAt

获取所有密钥

查询参数

响应

示例

响应：200 Ok

注意

获取一个密钥

路径参数

示例

响应：200 Ok

创建密钥

正文

示例

响应：201 Created

更新密钥

路径参数

正文

示例

响应：200 Ok

删除密钥

路径参数

示例

响应：204 No Content

这有帮助吗？

`name`

`description`

`uid`

`key`

`actions`

`indexes`

`expiresAt`

`createdAt`

`updatedAt`

响应：`200 Ok`

响应：`200 Ok`

响应：`201 Created`

响应：`200 Ok`

响应：`204 No Content`