返回首页v1.14文档

    密钥

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

    警告

    访问 /keys 路由而未设置主密钥将抛出 missing_master_key 错误。

    密钥对象

     
    {
  "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

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

    key

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

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

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

    在实例之间重用 API 密钥

    自定义 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提供对更新网络对象端点的访问权限

    索引

    类型: 数组
    默认值: 不适用
    描述：密钥被授权操作的索引数组。使用["*"] 代表所有索引。只有密钥的允许的操作才能在这些索引上使用。

    你也可以使用 * 字符作为通配符，方法是将其添加到字符串的末尾。这允许 API 密钥访问所有以此字符串开头的索引名称。例如，使用 "indexes": ["movie*"] 将使 API 密钥能够访问 movies 和 movie_ratings 索引。

    expiresAt

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

    注意

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

    createdAt

    类型: 字符串
    默认值: null
    描述：密钥创建的日期和时间，以 RFC 3339 格式表示。

    updatedAt

    类型: 字符串
    默认值: null
    描述：密钥最后更新的日期和时间，以 RFC 3339 格式表示。

    获取所有密钥
    GET/keys

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

    查询参数

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

    查询参数默认值描述
    offset0要跳过的密钥数量
    limit20要返回的密钥数量

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

    示例

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

    响应: 200 Ok

     
    {
  "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 'MEILISEARCH_URL/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

    响应: 200 Ok

     
    {
  "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 操作列表。 ["*"] 代表所有操作
    索引 *数组N/A密钥被授权操作的索引数组。 ["*"] 代表所有索引
    expiresAt *字符串N/A密钥过期的日期和时间，以 RFC 3339 格式表示。如果密钥永不过期，则为 null。
    name字符串null密钥的人工可读名称
    uid字符串N/A用于标识 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": "Add documents: Products API key",
    "actions": ["documents.add"],
    "indexes": ["products"],
    "expiresAt": "2042-04-02T00:42:42Z"
  }'

    响应: 201 Created

     
    {
  "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 密钥的名称和描述。

    密钥的更新是部分更新。这意味着您应该仅提供您打算更新的字段，因为 payload 中未出现的任何字段将保持不变。

    路径参数

    需要有效的 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 Ok

     
    {
  "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 'MEILISEARCH_URL/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

    响应: 204 No Content