スナップショットの復元（Restore snapshot）

スナップショットの復元API

クラスターまたは指定されたデータストリームとインデックスのsnapshotを復元します。

Python

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

Ruby

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

Js

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

Console

POST /_snapshot/my_repository/my_snapshot/_restore

Request

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

前提条件

• Elasticsearchのセキュリティ機能を使用している場合、このAPIを使用するにはmanageまたはcluster:admin/snapshot/*のクラスター権限が必要です。

• スナップショットは、選出されたマスターノードを持つ稼働中のクラスターにのみ復元できます。スナップショットのリポジトリは登録済みで、クラスターに利用可能でなければなりません。

• スナップショットとクラスターのバージョンは互換性がある必要があります。スナップショットの互換性を参照してください。
• スナップショットを復元するには、クラスターのグローバルメタデータが書き込み可能である必要があります。書き込みを防ぐクラスターブロックがないことを確認してください。復元操作はインデックスブロックを無視します。
• データストリームを復元する前に、クラスターにデータストリームが有効な一致するインデックステンプレートが含まれていることを確認してください。確認するには、Kibanaのインデックス管理機能またはget index template APIを使用します。

Python

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)

Ruby

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

Js

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);

Console

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
• (オプション、Boolean) trueの場合、リクエストは復元操作が完了したときに応答を返します。復元されたインデックスのプライマリシャードを回復するためのすべての試行が完了したときに操作が完了します。これは、1つ以上の回復試行が失敗した場合でも適用されます。
  falseの場合、リクエストは復元操作が初期化されたときに応答を返します。デフォルトはfalseです。

リクエストボディ

• ignore_unavailable
• (オプション、Boolean) trueの場合、リクエストはスナップショットから欠落しているindicesのインデックスまたはデータストリームを無視します。falseの場合、リクエストは欠落しているインデックスまたはデータストリームに対してエラーを返します。デフォルトはfalseです。
• ignore_index_settings
• (オプション、文字列または文字列の配列) スナップショットから復元しないインデックス設定。index.number_of_shards(0dd33dc5c1f7a36a.md#index-number-of-shards)を無視するためにこのオプションを使用することはできません。
  データストリームの場合、このオプションは復元されたバックインデックスにのみ適用されます。新しいバックインデックスはデータストリームの一致するインデックステンプレートを使用して構成されます。
• include_aliases

• (オプション、Boolean) trueの場合、リクエストは復元されたデータストリームとインデックスのエイリアスを復元します。falseの場合、リクエストはエイリアスを復元しません。デフォルトはtrueです。

• include_global_state

• (オプション、Boolean) trueの場合、クラスター状態を復元します。デフォルトはfalseです。
  クラスター状態には次が含まれます:

  • 永続的なクラスター設定
  • インデックステンプレート
  • レガシーインデックステンプレート
  • インジェストパイプライン
  • ILMポリシー
  • 保存されたスクリプト
  • 7.12.0以降に取得されたスナップショットの機能状態
    include_global_stateがtrueの場合、復元操作はクラスター内のレガシーインデックステンプレートをスナップショットに含まれるテンプレートとマージし、スナップショット内の名前と一致する既存のものを置き換えます。クラスター内に存在するすべての永続的な設定、非レガシーインデックステンプレート、インジェストパイプライン、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(0dd33dc5c1f7a36a.md#index-number-of-shards)を変更するためにこのオプションを使用することはできません。
  データストリームの場合、このオプションは復元されたバックインデックスにのみ適用されます。新しいバックインデックスはデータストリームの一致するインデックステンプレートを使用して構成されます。
• indices

• (オプション、文字列または文字列の配列) 復元するインデックスとデータストリームのカンマ区切りリスト。 マルチターゲット構文をサポートします。デフォルトはスナップショット内のすべての通常のインデックスと通常のデータストリームです。
  このパラメータを使用してシステムインデックスまたはシステムデータストリームを復元することはできません。feature_statesを代わりに使用してください。

• partial

• (オプション、Boolean) falseの場合、スナップショットに含まれるインデックスの1つ以上のプライマリシャードが利用できない場合、復元操作全体が失敗します。デフォルトは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に名前が変更されます。

Python

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)

Ruby

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

Js

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);

Console

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がno_valid_shard_copyを報告した後に代替オプションが表示されない場合です。

次のリクエストは、index_1を閉じるし、my_repositoryリポジトリのsnapshot_2スナップショットからインプレースで復元します。

Python

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)

Ruby

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

Js

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);

Console

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