› › ›

更新 API 密钥 API

编辑

更新 API 密钥 API编辑

请求编辑

PUT /_security/api_key/<id>

先决条件编辑

要使用此 API，您必须至少拥有 manage_own_api_key 集群权限。用户只能更新他们创建的或授予他们的 API 密钥。要更新其他用户的 API 密钥，请使用 run_as 功能代表其他用户提交请求。

无法使用 API 密钥作为此 API 的身份验证凭据。要更新 API 密钥，需要所有者用户的凭据。

描述编辑

使用此 API 更新由创建 API 密钥或授予 API 密钥 API 创建的 API 密钥。如果需要对多个 API 密钥应用相同的更新，可以使用批量更新 API 密钥以减少开销。

无法更新已过期的 API 密钥，或已由使 API 密钥无效使其无效的 API 密钥。

此 API 支持更新 API 密钥的访问范围、元数据和到期时间。API 密钥的访问范围来自您在请求中指定的 role_descriptors，以及请求时所有者用户权限的快照。所有者权限的快照会在每次调用时自动更新。

如果您未在请求中指定 role_descriptors，则调用此 API 仍可能会更改 API 密钥的访问范围。如果所有者用户的权限自创建或上次修改 API 密钥后已更改，则可能会发生此更改。

路径参数编辑

id: （必填，字符串）要更新的 API 密钥的 ID。

请求正文编辑

您可以在请求正文中指定以下参数，这是可选的。

role_descriptors: （可选，对象）要分配给此 API 密钥的角色描述符。API 密钥的有效权限是其分配的权限与所有者用户权限的时间点快照的交集。您可以通过在此参数中指定新权限来分配新权限。要删除分配的权限，您可以提供一个空的 role_descriptors 参数，即一个空对象 {}。如果 API 密钥没有分配的权限，则它将继承所有者用户的完整权限。无论您是否提供 role_descriptors 参数，所有者权限的快照始终都会更新。角色描述符的结构与创建 API 密钥 API 的请求相同。
metadata: （可选，对象）您要与 API 密钥关联的任意元数据。它支持嵌套数据结构。在 metadata 对象中，以 _ 开头的顶级键保留供系统使用。指定后，这将完全替换以前与 API 密钥关联的元数据。
expiration: （可选，字符串）API 密钥的到期时间。默认情况下，API 密钥永不过期。可以省略以保持不变。

响应正文编辑

updated: （布尔值）如果为 true，则 API 密钥已更新。如果为 false，则 API 密钥未更改，因为未检测到任何更改。

示例编辑

如果您创建 API 密钥，如下所示

POST /_security/api_key
{
  "name": "my-api-key",
  "role_descriptors": {
    "role-a": {
      "cluster": ["all"],
      "indices": [
        {
          "names": ["index-a*"],
          "privileges": ["read"]
        }
      ]
    }
  },
  "metadata": {
    "application": "my-application",
    "environment": {
       "level": 1,
       "trusted": true,
       "tags": ["dev", "staging"]
    }
  }
}

成功调用将返回一个 JSON 结构，其中提供 API 密钥信息。例如

{
  "id": "VuaCfGcBCdbkQm-e5aOx",
  "name": "my-api-key",
  "api_key": "ui2lp2axTNmsyakw9tvNnw",
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}

对于以下示例，假设所有者用户的权限为

{
  "cluster": ["all"],
  "indices": [
    {
      "names": ["*"],
      "privileges": ["all"]
    }
  ]
}

以下示例更新了上面创建的 API 密钥，为其分配了新的角色描述符和元数据

PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
{
  "role_descriptors": {
    "role-a": {
      "indices": [
        {
          "names": ["*"],
          "privileges": ["write"]
        }
      ]
    }
  },
  "metadata": {
    "environment": {
       "level": 2,
       "trusted": true,
       "tags": ["production"]
    }
  }
}

成功调用将返回一个 JSON 结构，指示 API 密钥已更新

{
  "updated": true
}

更新后，API 密钥的有效权限将是提供的角色描述符与所有者用户权限的交集

{
  "indices": [
    {
      "names": ["*"],
      "privileges": ["write"]
    }
  ]
}

以下示例删除了 API 密钥先前分配的权限，使其继承所有者用户的完整权限。

PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
{
  "role_descriptors": {}
}

返回以下响应

{
  "updated": true
}

更新后，API 密钥的有效权限将与所有者用户的权限相同

{
  "cluster": ["all"],
  "indices": [
    {
      "names": ["*"],
      "privileges": ["all"]
    }
  ]
}

对于下一个示例，假设所有者用户的权限已从原始权限更改为

{
  "cluster": ["manage_security"],
  "indices": [
    {
      "names": ["*"],
      "privileges": ["read"]
    }
  ]
}

以下请求自动更新与 API 密钥关联的用户权限快照

PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx

返回以下响应

{
  "updated": true
}

导致 API 密钥具有以下有效权限

{
  "cluster": ["manage_security"],
  "indices": [
    {
      "names": ["*"],
      "privileges": ["read"]
    }
  ]
}

« 查询用户 API 更新安全索引设置 »