New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 查询用户 API 更新安全索引设置 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST APIs ›安全 API

更新 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 密钥

resp = client.security.create_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"
            ]
        }
    },
)
print(resp)
const response = await client.security.createApiKey({
  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"],
    },
  },
});
console.log(response);
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"]
    }
  }
}
Copy as curlTry in Elastic 

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

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

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

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

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

resp = client.security.update_api_key(
    id="VuaCfGcBCdbkQm-e5aOx",
    role_descriptors={
        "role-a": {
            "indices": [
                {
                    "names": [
                        "*"
                    ],
                    "privileges": [
                        "write"
                    ]
                }
            ]
        }
    },
    metadata={
        "environment": {
            "level": 2,
            "trusted": True,
            "tags": [
                "production"
            ]
        }
    },
)
print(resp)
const response = await client.security.updateApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
  role_descriptors: {
    "role-a": {
      indices: [
        {
          names: ["*"],
          privileges: ["write"],
        },
      ],
    },
  },
  metadata: {
    environment: {
      level: 2,
      trusted: true,
      tags: ["production"],
    },
  },
});
console.log(response);
PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
{
  "role_descriptors": {
    "role-a": {
      "indices": [
        {
          "names": ["*"],
          "privileges": ["write"]
        }
      ]
    }
  },
  "metadata": {
    "environment": {
       "level": 2,
       "trusted": true,
       "tags": ["production"]
    }
  }
}
Copy as curlTry in Elastic 

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

{
  "updated": true
}

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

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

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

resp = client.security.update_api_key(
    id="VuaCfGcBCdbkQm-e5aOx",
    role_descriptors={},
)
print(resp)
const response = await client.security.updateApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
  role_descriptors: {},
});
console.log(response);
PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
{
  "role_descriptors": {}
}
Copy as curlTry in Elastic 

这将返回响应

{
  "updated": true
}

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

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

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

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

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

resp = client.security.update_api_key(
    id="VuaCfGcBCdbkQm-e5aOx",
)
print(resp)
const response = await client.security.updateApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
});
console.log(response);
PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
Copy as curlTry in Elastic 

这将返回响应

{
  "updated": true
}

从而导致 API 密钥的以下有效权限

{
  "cluster": ["manage_security"],
  "indices": [
    {
      "names": ["*"],
      "privileges": ["read"]
    }
  ]
}
« 查询用户 API 更新安全索引设置 »

On this page

Was this helpful?
Feedback