› › ›

API массового обновления ключей API

Запрос

POST /_security/api_key/_bulk_update

Предварительные условия

Для использования этого API необходимо обладать как минимум привилегией кластера manage_own_api_key. Пользователи могут обновлять только ключи API, созданные ими или предоставленные им. Для обновления ключа API другого пользователя используйте функцию run_as, чтобы отправить запрос от имени другого пользователя.

Невозможно использовать ключ API в качестве аутентификационного средства для этого API. Для обновления ключей API требуется учетные данные пользователя-владельца.

Описание

Этот API аналогичен API обновления одного ключа API, но позволяет применить одно и то же обновление к нескольким ключам API в одном вызове API. Это значительно повышает производительность по сравнению с отдельными обновлениями.

Невозможно обновить истекшие или аннулированные ключи API.

Этот API поддерживает обновления области доступа ключа API, метаданных и срока действия. Область доступа каждого ключа API определяется из role_descriptors, указанного в запросе, и моментального снимка разрешений пользователя-владельца на момент запроса. Моментальный снимок разрешений владельца обновляется автоматически при каждом вызове.

Если вы не укажете role_descriptors в запросе, вызов этого API все равно может изменить область доступа ключа API. Это изменение может произойти, если разрешения пользователя-владельца изменились с момента создания или последнего изменения ключа API.

Тело запроса

В теле запроса можно указать следующие параметры.

ids: (Обязательно, список) Идентификаторы ключей API, которые нужно обновить.

role_descriptors: (Необязательно, объект) Описатели ролей, которые нужно назначить ключам API. Эффективные разрешения ключа API являются пересечением назначенных привилегий и моментального снимка разрешений пользователя-владельца. Вы можете назначить новые привилегии, указав их в этом параметре. Чтобы удалить назначенные привилегии, укажите параметр role_descriptors как пустой объект {}. Если у ключа API нет назначенных привилегий, он наследует полные разрешения пользователя-владельца. Моментальный снимок разрешений владельца всегда обновляется, независимо от того, указываете вы параметр role_descriptors или нет. Структура описателя роли аналогична запросу для API создания ключей API.
metadata: (Необязательно, объект) Произвольные вложенные метаданные для ассоциации с ключами API.

Внутри объекта metadata, имена ключей, начинающиеся с подчеркивания (_), зарезервированы для использования системой. Любая информация, указанная в этом параметре, полностью заменяет метаданные, ранее ассоциированные с ключом API.

expiration: (Необязательно, строка) Время истечения срока действия ключей API. По умолчанию ключи API никогда не истекают. Можно опустить, чтобы оставить без изменений.

Тело ответа

Успешный запрос возвращает JSON-структуру, содержащую идентификаторы всех обновленных ключей API, идентификаторы ключей API, которые уже имели запрошенные изменения и не требуют обновления, и подробности об ошибках для любых неудачных обновлений.

Примеры

В примерах ниже предполагается, что пользователь создает два ключа 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"]
    }
  }
}

Это приводит к ответу с приведенной ниже информацией о ключе API.

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

Пользователь создает второй ключ API:

resp = client.security.create_api_key(
    name="my-other-api-key",
    metadata={
        "application": "my-application",
        "environment": {
            "level": 2,
            "trusted": True,
            "tags": [
                "dev",
                "staging"
            ]
        }
    },
)
print(resp)

const response = await client.security.createApiKey({
  name: "my-other-api-key",
  metadata: {
    application: "my-application",
    environment: {
      level: 2,
      trusted: true,
      tags: ["dev", "staging"],
    },
  },
});
console.log(response);

POST /_security/api_key
{
  "name": "my-other-api-key",
  "metadata": {
    "application": "my-application",
    "environment": {
       "level": 2,
       "trusted": true,
       "tags": ["dev", "staging"]
    }
  }
}

Результат — информация о ключе API:

{
  "id": "H3_AhoIBA9hmeQJdg7ij",
  "name": "my-other-api-key",
  "api_key": "134G4ilmT_uGWXHRfJfXXA",
  "encoded": "SDNfQWhvSUJBOWhtZVFKZGc3aWo6MTM0RzRpbG1UX3VHV1hIUmZKZlhYQQ=="
}

Кроме того, предположим, что разрешения пользователя-владельца:

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

Следующий пример обновляет созданные выше ключи API, назначая им новые описатели ролей, метаданные и обновляет срок их действия.

resp = client.security.bulk_update_api_keys(
    ids=[
        "VuaCfGcBCdbkQm-e5aOx",
        "H3_AhoIBA9hmeQJdg7ij"
    ],
    role_descriptors={
        "role-a": {
            "indices": [
                {
                    "names": [
                        "*"
                    ],
                    "privileges": [
                        "write"
                    ]
                }
            ]
        }
    },
    metadata={
        "environment": {
            "level": 2,
            "trusted": True,
            "tags": [
                "production"
            ]
        }
    },
    expiration="30d",
)
print(resp)

const response = await client.transport.request({
  method: "POST",
  path: "/_security/api_key/_bulk_update",
  body: {
    ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
    role_descriptors: {
      "role-a": {
        indices: [
          {
            names: ["*"],
            privileges: ["write"],
          },
        ],
      },
    },
    metadata: {
      environment: {
        level: 2,
        trusted: true,
        tags: ["production"],
      },
    },
    expiration: "30d",
  },
});
console.log(response);

POST /_security/api_key/_bulk_update
{
  "ids": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ],
  "role_descriptors": {
    "role-a": {
      "indices": [
        {
          "names": ["*"],
          "privileges": ["write"]
        }
      ]
    }
  },
  "metadata": {
    "environment": {
       "level": 2,
       "trusted": true,
       "tags": ["production"]
    }
  },
  "expiration": "30d"
}

Успешный вызов возвращает JSON-структуру, указывающую, что ключи API были обновлены:

{
  "updated": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ],
  "noops": []
}

Эффективные разрешения обоих ключей API после обновления будут пересечением предоставленных описателей ролей и разрешений пользователя-владельца:

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

Следующий пример удаляет ранее назначенные разрешения ключей API, заставляя их наследоваться от полных разрешений пользователя-владельца.

resp = client.security.bulk_update_api_keys(
    ids=[
        "VuaCfGcBCdbkQm-e5aOx",
        "H3_AhoIBA9hmeQJdg7ij"
    ],
    role_descriptors={},
)
print(resp)

const response = await client.transport.request({
  method: "POST",
  path: "/_security/api_key/_bulk_update",
  body: {
    ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
    role_descriptors: {},
  },
});
console.log(response);

POST /_security/api_key/_bulk_update
{
  "ids": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ],
  "role_descriptors": {}
}

Что возвращает ответ:

{
  "updated": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ],
  "noops": []
}

Эффективные разрешения ключей API после обновления будут такими же, как у пользователя-владельца:

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

В следующем примере предполагается, что разрешения пользователя-владельца изменились с исходных разрешений на:

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

Следующий запрос автоматически обновляет моментальный снимок разрешений пользователя, связанных с двумя ключами API.

resp = client.security.bulk_update_api_keys(
    ids=[
        "VuaCfGcBCdbkQm-e5aOx",
        "H3_AhoIBA9hmeQJdg7ij"
    ],
)
print(resp)

const response = await client.transport.request({
  method: "POST",
  path: "/_security/api_key/_bulk_update",
  body: {
    ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
  },
});
console.log(response);

POST /_security/api_key/_bulk_update
{
  "ids": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ]
}

Что возвращает ответ:

{
  "updated": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ],
  "noops": []
}

В результате следующие эффективные разрешения для обоих ключей API:

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

Если какой-либо ключ API не удается обновить, подробности об ошибке включаются в поле errors. Например:

{
  "updated": ["VuaCfGcBCdbkQm-e5aOx"],
  "noops": [],
  "errors": { 
    "count": 3,
    "details": {
       "g_PqP4IBcBaEQdwM5-WI": { 
         "type": "resource_not_found_exception",
         "reason": "no API key owned by requesting user found for ID [g_PqP4IBcBaEQdwM5-WI]"
       },
       "OM4cg4IBGgpHBfLerY4B": {
         "type": "illegal_argument_exception",
         "reason": "cannot update invalidated API key [OM4cg4IBGgpHBfLerY4B]"
       },
       "Os4gg4IBGgpHBfLe2I7j": {
         "type": "exception",
         "reason": "bulk request execution failure",
         "caused_by": { 
           "type" : "version_conflict_engine_exception",
           "reason" : "[1]: version conflict, required seqNo [1], primary term [1]. current document has seqNo [2] and primary term [1]"
         }
       }
    }
  }
}

	Это поле отсутствует в ответе, когда `count` равно 0.
	Идентификатор ключа API, для которого произошла ошибка.
	Подробности об ошибке также могут включать поле `caused_by`.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-bulk-update-api-keys.html