› › ›

API обновления ключа API для межкластерного доступа

Обновление существующего ключа API для межкластерного доступа, используемого для доступа к удалённым кластерам с помощью аутентификации по ключу API.

Запрос

PUT /_security/cross_cluster/api_key/<id>

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

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

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

Описание

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

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

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

Параметры пути

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

Тело запроса

В теле запроса можно указать следующие параметры. Параметры необязательны, но не все из них могут быть отсутствовать.

access: (Необязательно, объект) Доступ, который необходимо предоставить этому ключу API. Доступ состоит из разрешений для межкластерного поиска и межкластерной репликации. По крайней мере, одно из них должно быть указано. При указании новое назначение доступа полностью заменяет ранее назначенный доступ. Обратитесь к параметру параметра API создания ключа API для межкластерного доступа для структуры поля.
metadata: (Необязательно, объект) Произвольные метаданные, которые вы хотите связать с ключом API. Поддерживает вложенные структуры данных. Внутри объекта metadata, верхнеуровневые ключи, начинающиеся с _, зарезервированы для использования системой. При указании это полностью заменяет метаданные, ранее связанные с ключом API.
expiration: (Необязательно, строка) Время истечения срока действия ключа API. По умолчанию ключи API никогда не истекают. Можно опустить, чтобы оставить без изменений.

Тело ответа

updated: (булево) Если true, ключ API был обновлён. Если false, ключ API не изменился, так как изменений не было обнаружено.

Примеры

Если вы создаёте ключ API для межкластерного доступа следующим образом:

resp = client.perform_request(
    "POST",
    "/_security/cross_cluster/api_key",
    headers={"Content-Type": "application/json"},
    body={
        "name": "my-cross-cluster-api-key",
        "access": {
            "search": [
                {
                    "names": [
                        "logs*"
                    ]
                }
            ]
        },
        "metadata": {
            "application": "search"
        }
    },
)
print(resp)

const response = await client.transport.request({
  method: "POST",
  path: "/_security/cross_cluster/api_key",
  body: {
    name: "my-cross-cluster-api-key",
    access: {
      search: [
        {
          names: ["logs*"],
        },
      ],
    },
    metadata: {
      application: "search",
    },
  },
});
console.log(response);

POST /_security/cross_cluster/api_key
{
  "name": "my-cross-cluster-api-key",
  "access": {
    "search": [
      {
        "names": ["logs*"]
      }
    ]
  },
  "metadata": {
    "application": "search"
  }
}

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

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

Информацию о ключе API, включая точный описатель роли, можно проверить с помощью API получения информации о ключе API

resp = client.security.get_api_key(
    id="VuaCfGcBCdbkQm-e5aOx",
)
print(resp)

const response = await client.security.getApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
});
console.log(response);

GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx

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

{
  "api_keys": [
    {
      "id": "VuaCfGcBCdbkQm-e5aOx",
      "name": "my-cross-cluster-api-key",
      "type": "cross_cluster",
      "creation": 1548550550158,
      "expiration": null,
      "invalidated": false,
      "username": "myuser",
      "realm": "native1",
      "metadata": {
        "application": "search"
      },
      "role_descriptors": {
        "cross_cluster": {  
          "cluster": [
              "cross_cluster_search"
          ],
          "indices": [
            {
              "names": [
                "logs*"
              ],
              "privileges": [
                "read", "read_cross_cluster", "view_index_metadata"
              ],
              "allow_restricted_indices": false
            }
          ],
          "applications": [ ],
          "run_as": [ ],
          "metadata": { },
          "transient_metadata": {
            "enabled": true
          }
        }
      },
      "access": {  
        "search": [
          {
            "names": [
              "logs*"
            ],
            "allow_restricted_indices": false
          }
        ]
      }
    }
  ]
}

	Описание роли, соответствующее указанному в момент создания `access` области доступа. В этом примере он предоставляет разрешение на межкластерный поиск для шаблона индекса `logs*`.
	`access` соответствует значению, указанному при создании ключа API.

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

resp = client.perform_request(
    "PUT",
    "/_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx",
    headers={"Content-Type": "application/json"},
    body={
        "access": {
            "replication": [
                {
                    "names": [
                        "archive"
                    ]
                }
            ]
        },
        "metadata": {
            "application": "replication"
        }
    },
)
print(resp)

const response = await client.transport.request({
  method: "PUT",
  path: "/_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx",
  body: {
    access: {
      replication: [
        {
          names: ["archive"],
        },
      ],
    },
    metadata: {
      application: "replication",
    },
  },
});
console.log(response);

PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx
{
  "access": {
    "replication": [
      {
        "names": ["archive"]
      }
    ]
  },
  "metadata": {
    "application": "replication"
  }
}

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

{
  "updated": true
}

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

{
  "api_keys": [
    {
      "id": "VuaCfGcBCdbkQm-e5aOx",
      "name": "my-cross-cluster-api-key",
      "type": "cross_cluster",
      "creation": 1548550550158,
      "expiration": null,
      "invalidated": false,
      "username": "myuser",
      "realm": "native1",
      "metadata": {
        "application": "replication"
      },
      "role_descriptors": {
        "cross_cluster": {  
          "cluster": [
              "cross_cluster_replication"
          ],
          "indices": [
            {
              "names": [
                "archive*"
              ],
              "privileges": [
                "cross_cluster_replication", "cross_cluster_replication_internal"
              ],
              "allow_restricted_indices": false
            }
          ],
          "applications": [ ],
          "run_as": [ ],
          "metadata": { },
          "transient_metadata": {
            "enabled": true
          }
        }
      },
      "access": {  
        "replication": [
          {
            "names": [
              "archive*"
            ],
            "allow_restricted_indices": false
          }
        ]
      }
    }
  ]
}

	Описание роли обновлено на `access` область доступа, указанную при обновлении. В этом примере он обновляется, чтобы предоставить разрешение на межкластерную репликацию для шаблона индекса `archive*`.
	`access` соответствует значению, указанному при обновлении ключа API.

© 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-update-cross-cluster-api-key.html