密钥

/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"
}

`名称`

类型：字符串
默认值：null
描述：密钥的人类可读名称

`描述`

类型：字符串
默认值：null
描述：密钥的描述。您可以在此处添加有关密钥的任何重要信息

`UID`

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

`密钥`

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

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

注意

由于key是uid和主密钥的哈希值，因此在共享相同配置的实例之间，key的值是确定的。您可以使用以下命令确定 API 密钥的值，将HYPHENATED_UUID和MASTER_KEY替换为您密钥和实例的正确值。

echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY

这也意味着，如果主密钥发生更改，所有key的值都会自动更改。

`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`	整数	跳过的密钥数量
`limit`	整数	返回的密钥数量
`total`	整数	API 密钥的总数

示例

curl \
  -X GET 'http://localhost: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。

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

示例

curl \
  -X GET 'http://localhost: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` *	数组	N/A	密钥允许执行的 API 操作列表。`["*"]`表示所有操作。
`indexes` *	数组	N/A	密钥被授权操作的索引数组。`["*"]`表示所有索引。
`expiresAt` *	字符串	N/A	密钥过期的时间和日期，以RFC 3339格式表示。如果密钥永不过期，则为`null`。
`名称`	字符串	`null`	密钥的可读名称。
`UID`	字符串	N/A	使用 uuid v4 来标识 API 密钥。如果未指定，则由 Meilisearch 生成。
`描述`	字符串	`null`	密钥的可选描述。

示例

curl \
  -X POST 'http://localhost: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 已创建`

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。

密钥更新是部分的。这意味着您应该只提供您想要更新的字段，因为有效负载中不存在的任何字段将保持不变。

路径参数

需要有效的 API key或uid。

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

主体

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

示例

curl \
  -X PATCH 'http://localhost: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。

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

示例

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

响应：`204 无内容`

编辑此页面

这有帮助吗？

想包含更多细节？在我们的公共文档仓库中提交问题。

密钥

警告

密钥对象

`名称`

`描述`

`UID`

`密钥`

注意

`actions`

警告

`indexes`

`expiresAt`

注意

`createdAt`

`updatedAt`

获取所有密钥

查询参数

响应

示例

响应：`200 Ok`

注意

获取单个密钥

路径参数

示例

响应：`200 Ok`

创建密钥

主体

示例

响应：`201 已创建`

更新密钥

路径参数

主体

示例

响应：`200 Ok`

删除密钥

路径参数

示例

响应：`204 无内容`

这有帮助吗？

密钥

警告

密钥对象

名称

描述

UID

密钥

注意

actions

警告

indexes

expiresAt

注意

createdAt

updatedAt

获取所有密钥

查询参数

响应

示例

响应：200 Ok

注意

获取单个密钥

路径参数

示例

响应：200 Ok

创建密钥

主体

示例

响应：201 已创建

更新密钥

路径参数

主体

示例

响应：200 Ok

删除密钥

路径参数

示例

响应：204 无内容

这有帮助吗？

`名称`

`描述`

`UID`

`密钥`

`actions`

`indexes`

`expiresAt`

`createdAt`

`updatedAt`

响应：`200 Ok`

响应：`200 Ok`

响应：`201 已创建`

响应：`200 Ok`

响应：`204 无内容`