› › ›

API восстановления снимка

Восстанавливает снимок кластера или указанных потоков данных и индексов.

resp = client.snapshot.restore(
    repository="my_repository",
    snapshot="my_snapshot",
)
print(resp)

response = client.snapshot.restore(
  repository: 'my_repository',
  snapshot: 'my_snapshot'
)
puts response

const response = await client.snapshot.restore({
  repository: "my_repository",
  snapshot: "my_snapshot",
});
console.log(response);

POST /_snapshot/my_repository/my_snapshot/_restore

Запрос

POST /_snapshot/<repository>/<snapshot>/_restore

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

При использовании функций безопасности Elasticsearch необходимо иметь право manage или cluster:admin/snapshot/* на уровне кластера для использования этого API.

Вы можете восстановить снимок только в работающем кластере с выбранным мастер-узлом. Репозиторий снимка должен быть зарегистрирован и доступен для кластера.
Версии снимка и кластера должны быть совместимы. См. Совместимость снимков.
Для восстановления снимка глобальные метаданные кластера должны быть доступны для записи. Убедитесь, что нет блокировок кластера, которые препятствуют записям. Операция восстановления игнорирует блокировки индексов.
Перед восстановлением потока данных убедитесь, что кластер содержит соответствующую шаблон индекса с включенным потоком данных. Для проверки используйте функцию Управление индексами Kibana или API получения шаблона индекса:
```
resp = client.indices.get_index_template(
    name="*",
    filter_path="index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream",
)
print(resp)
```
```
response = client.indices.get_index_template(
  name: '*',
  filter_path: 'index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream'
)
puts response
```
```
const response = await client.indices.getIndexTemplate({
  name: "*",
  filter_path:
    "index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream",
});
console.log(response);
```
```
GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream
```
Если такого шаблона нет, вы можете создать его или восстановить состояние кластера, содержащее его. Без соответствующего шаблона индекса поток данных не может перезаписываться или создавать поддерживающие индексы.
Если ваш снимок содержит данные из App Search или Workplace Search, убедитесь, что вы восстановили ключ шифрования Enterprise Search перед восстановлением снимка.

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

<repository>: (Обязательно, строка) Имя репозитория для восстановления снимка.
<snapshot>: (Обязательно, строка) Имя снимка для восстановления.

Параметры запроса

master_timeout

(Необязательно, единицы времени) Период ожидания мастер-узла. Если мастер-узел недоступен до истечения срока ожидания, запрос завершается ошибкой. По умолчанию 30s. Также может быть установлен на -1, чтобы указать, что запрос никогда не должен вызывать таймаут.

wait_for_completion

(Необязательно, Булево) Если true, запрос возвращает ответ, когда операция восстановления завершается. Операция считается завершенной, когда она завершает все попытки восстановления основных фрагментов для восстановленных индексов. Это относится даже в том случае, если одна или несколько попыток восстановления завершаются ошибкой.

Если false, запрос возвращает ответ, когда операция восстановления инициализируется. По умолчанию false.

Тело запроса

ignore_unavailable

(Необязательно, булево) Если true, запрос игнорирует любой отсутствующий индекс или поток данных в indices в снимке. Если false, запрос возвращает ошибку для любого отсутствующего индекса или потока данных. По умолчанию false.

ignore_index_settings

(Необязательно, строка или массив строк) Настройки индексов, которые не нужно восстанавливать из снимка. Вы не можете использовать этот параметр для игнорирования index.number_of_shards.

Для потоков данных этот параметр применяется только к восстанавливаемым фоновым индексам. Новые фоновые индексы настраиваются с использованием соответствующей шаблона индекса потока данных.

include_aliases

(Необязательно, булево) Если true, запрос восстанавливает алиасы для всех восстановленных потоков данных и индексов. Если false, запрос не восстанавливает алиасы. По умолчанию true.

include_global_state

(Необязательно, булево) Если true, восстановить состояние кластера. По умолчанию false.

Состояние кластера включает:

Постоянные настройки кластера
Шаблоны индексов
Устаревшие шаблоны индексов
Конвейеры Ingest
Политики ILM
Сохраненные скрипты
Для снимков, сделанных после 7.12.0, состояния функций

Если include_global_state равно true, то операция восстановления объединяет устаревшие шаблоны индексов в вашем кластере с шаблонами, содержащимися в снимке, заменяя любые существующие шаблоны с совпадающим именем. Она полностью удаляет все постоянные настройки, шаблоны индексов (не устаревшие), конвейеры Ingest и политики ILM жизненного цикла, существующие в вашем кластере, и заменяет их соответствующими элементами из снимка.

Используйте параметр feature_states для настройки того, как восстанавливаются состояния функций.

Если include_global_state равно true, и снимок был создан без глобального состояния, запрос на восстановление завершится ошибкой.

feature_states

(Необязательно, массив строк) Состояния функций для восстановления.

Если include_global_state равно true, запрос по умолчанию восстанавливает все состояния функций из снимка. Если include_global_state равно false, запрос по умолчанию не восстанавливает состояния функций. Обратите внимание, что указание пустого массива приведет к поведению по умолчанию. Для восстановления без состояний функций, независимо от значения include_global_state, укажите массив, содержащий только значение none (["none"]).

index_settings

(Необязательно, объект) Настройки индексов для добавления или изменения в восстановленных индексах, включая фоновые индексы. Вы не можете использовать этот параметр для изменения index.number_of_shards.

Для потоков данных этот параметр применяется только к восстановленным фоновым индексам. Новые фоновые индексы настраиваются с использованием соответствующей шаблона индекса потока данных.

indices

(Необязательно, строка или массив строк) Список индексов и потоков данных для восстановления, разделенный запятыми. Поддерживает синтаксис для множественных целей. По умолчанию все обычные индексы и обычные потоки данных в снимке.

Вы не можете использовать этот параметр для восстановления системных индексов или системных потоков данных. Используйте feature_states вместо этого.

partial

(Необязательно, булево) Если false, вся операция восстановления завершится ошибкой, если один или несколько индексов в снимке не содержат всех доступных первичных фрагментов. По умолчанию false.

Если true, позволяет восстановить частичный снимок индексов с недоступными фрагментами. Будут восстановлены только фрагменты, успешно включенные в снимок. Все отсутствующие фрагменты будут созданы как пустые.

rename_pattern

(Необязательно, строка) Определяет шаблон переименования для восстановленных потоков данных и индексов. Потоки данных и индексы, соответствующие шаблону переименования, будут переименованы в соответствии с rename_replacement.

Шаблон переименования применяется в соответствии с регулярным выражением, поддерживающим ссылку на исходный текст, в соответствии с логикой appendReplacement.

rename_replacement: (Необязательно, строка) Определяет строку замены переименования. См. rename_pattern для получения дополнительной информации.

Примеры

Восстановление с переименованием

Следующий запрос восстанавливает index_1 и index_2 из snapshot_2. Параметры rename_pattern и rename_replacement указывают, что любой индекс, соответствующий регулярному выражению index_(.+), будет переименован с помощью шаблона restored_index_$1 при восстановлении.

Например, index_1 будет переименован в restored_index_1. index_2 будет переименован в restored_index_2.

resp = client.snapshot.restore(
    repository="my_repository",
    snapshot="snapshot_2",
    wait_for_completion=True,
    indices="index_1,index_2",
    ignore_unavailable=True,
    include_global_state=False,
    rename_pattern="index_(.+)",
    rename_replacement="restored_index_$1",
    include_aliases=False,
)
print(resp)

response = client.snapshot.restore(
  repository: 'my_repository',
  snapshot: 'snapshot_2',
  wait_for_completion: true,
  body: {
    indices: 'index_1,index_2',
    ignore_unavailable: true,
    include_global_state: false,
    rename_pattern: 'index_(.+)',
    rename_replacement: 'restored_index_$1',
    include_aliases: false
  }
)
puts response

const response = await client.snapshot.restore({
  repository: "my_repository",
  snapshot: "snapshot_2",
  wait_for_completion: "true",
  indices: "index_1,index_2",
  ignore_unavailable: true,
  include_global_state: false,
  rename_pattern: "index_(.+)",
  rename_replacement: "restored_index_$1",
  include_aliases: false,
});
console.log(response);

POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true
{
  "indices": "index_1,index_2",
  "ignore_unavailable": true,
  "include_global_state": false,
  "rename_pattern": "index_(.+)",
  "rename_replacement": "restored_index_$1",
  "include_aliases": false
}

API возвращает подтверждение, если запрос успешен. Если запрос обнаруживает ошибки, ответ указывает на любые проблемы, такие как открытые индексы, которые блокируют завершение операции восстановления.

Восстановление на месте

Возможно, вам потребуется восстановить индекс на месте, например, когда после использования API Cluster allocation explain не появляются альтернативные варианты, и он сообщает о no_valid_shard_copy.

Следующий запрос закрывает index_1, а затем восстанавливает его на месте из снимка snapshot_2 в хранилище my_repository.

resp = client.indices.close(
    index="index_1",
)
print(resp)

resp1 = client.snapshot.restore(
    repository="my_repository",
    snapshot="snapshot_2",
    wait_for_completion=True,
    indices="index_1",
)
print(resp1)

response = client.indices.close(
  index: 'index_1'
)
puts response

response = client.snapshot.restore(
  repository: 'my_repository',
  snapshot: 'snapshot_2',
  wait_for_completion: true,
  body: {
    indices: 'index_1'
  }
)
puts response

const response = await client.indices.close({
  index: "index_1",
});
console.log(response);

const response1 = await client.snapshot.restore({
  repository: "my_repository",
  snapshot: "snapshot_2",
  wait_for_completion: "true",
  indices: "index_1",
});
console.log(response1);

POST index_1/_close

POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true
{
  "indices": "index_1"
}

© 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/restore-snapshot-api.html

END_OF_DOCUMENT_MARKER