データのエクスポートとインポート

Cloud Firestore のマネージドエクスポート / インポートサービスを使用すると、誤って削除したデータを復元したり、オフライン処理用のデータをエクスポートしたりできます。すべてのドキュメントをエクスポートすることも、特定のコレクションだけをエクスポートすることもできます。同様に、エクスポートされたすべてのデータのインポートや、特定のコレクションのみのインポートも可能です。また、Cloud Firestore データベースからエクスポートされたデータを別の Cloud Firestore データベースにインポートすることもできます。Cloud Firestore のエクスポートを BigQuery に読み込むこともできます。

このページでは、マネージドエクスポート / インポートサービスと Cloud Storage を利用して、Cloud Firestore ドキュメントをエクスポートおよびインポートする方法について説明します。Cloud Firestore マネージドエクスポート / インポートサービスは、gcloud コマンドラインツールと Cloud Firestore API（REST、RPC）から利用できます。

始める前に

マネージドエクスポート / インポートサービスを使用するには、事前に次のタスクを完了する必要があります。

Google Cloud Platform プロジェクトに対する課金を有効にします。エクスポートとインポートの機能を使用できるのは、課金が有効になっている GCP プロジェクトのみです。
注: マネージドエクスポート / インポートサービスを使用するには、Firebase プロジェクトに Blaze プランが設定されている必要があります。Google Cloud Platform の請求を有効にすると、Firebase プロジェクトが自動的に Blaze プランにアップグレードされます。
お使いの Cloud Firestore データベースのロケーションの近くにあるロケーションに、プロジェクトの Cloud Storage バケットを作成します。エクスポート / インポートオペレーションには、リクエスト元による支払いバケットは使用できません。
Cloud Firestore と Cloud Storage の操作に必要な権限がアカウントに付与されていることを確認します。プロジェクトオーナーであれば、アカウントに必要な権限が付与されています。 それ以外の場合は、次の役割を指定して、エクスポートオペレーション、インポートオペレーション、Cloud Storage へのアクセスに必要な権限を付与できます。
- Cloud Firestore の役割: Owner、Cloud Datastore Owner、または Cloud Datastore Import Export Admin
  注: これらの Cloud Datastore の役割は、Cloud Firestore にも権限を付与します。
- Cloud Storage の役割: Owner または Storage Admin

プロジェクトに `gcloud` を設定する

次のいずれかの方法で gcloud コマンドラインツールを設定し、プロジェクトに接続します。

Cloud Shell を使用して、Google Cloud Platform Console から gcloud にアクセスします。

Cloud Shell の起動

正しいプロジェクトに gcloud が構成されていることを確認します。
```
gcloud config set project [PROJECT_ID]
```
Google Cloud SDK をインストールして初期化します。

gcloud beta コンポーネントがまだインストールされていない場合は追加します。このコンポーネントには、Cloud Firestore エクスポート / インポートコマンドが含まれています。

  gcloud components install beta

データをエクスポートする

エクスポートを実行すると、データベース内のドキュメントが Cloud Storage バケットの一連のファイルにコピーされます。エクスポートは、エクスポート開始時に取得された正確なデータベーススナップショットではありません。エクスポートには、オペレーションの実行中に追加された変更が含まれる場合があります。

すべてのドキュメントをエクスポートする

firestore export コマンドを使用してデータベース内のすべてのドキュメントをエクスポートします。[BUCKET_NAME] は Cloud Storage バケットの名前に置き換えてください。--async フラグを追加すると、gcloud ツールはオペレーションの完了を待機しません。

gcloud beta firestore export gs://[BUCKET_NAME]

バケット名の後にファイル接頭辞（たとえば、BUCKET_NAME/my-exports-folder/export-name）を追加すると、エクスポートを整理できます。ファイル接頭辞を指定しない場合、マネージドエクスポートサービスは現在のタイムスタンプに基づいてエクスポートを作成します。

エクスポートを開始すると、ターミナルを閉じても処理はキャンセルされません。オペレーションのキャンセルをご覧ください。

特定のコレクションをエクスポートする

特定のコレクショングループをエクスポートするには、--collection-ids フラグを使用します。このオペレーションでエクスポートされるのは、指定したコレクション ID を持つコレクショングループのみです。コレクショングループには、指定したコレクション ID を持つすべてのコレクションとサブコレクション（任意のパス上）が含まれます。

gcloud beta firestore export gs://[BUCKET_NAME] --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]

データをインポートする

Cloud Storage にファイルをエクスポートすると、これらのファイルのドキュメントをプロジェクトまたは別のプロジェクトにインポートできます。インポートでは、次の点に注意してください。

データをインポートすると、データベースの現在のインデックス定義を使用して必要なインデックスが更新されます。エクスポートにインデックスの定義は含まれません。
インポートでは、新しいドキュメント ID が割り当てられません。インポートでは、エクスポート時に取得された ID を使用します。ドキュメントをインポートするときに、ドキュメントの ID が予約され、ID の競合が防止されます。同じ ID のドキュメントがすでに存在する場合、インポートを行うと既存のドキュメントが上書きされます。
データベース内のドキュメントがインポートの影響を受けない場合、そのドキュメントはインポート後もデータベースに維持されます。

エクスポートからすべてのドキュメントをインポートする

以前のエクスポートからドキュメントをインポートするには、firestore import コマンドを使用します。

gcloud beta firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

[BUCKET_NAME] と [EXPORT_PREFIX] はエクスポートファイルの場所を表します。次に例を示します。

gcloud beta firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

エクスポートファイルの場所は、Google Cloud Platform Console の Cloud Storage ブラウザで確認できます。

Cloud Storage ブラウザを開く

インポートを開始すると、ターミナルを閉じても処理はキャンセルされません。オペレーションのキャンセルをご覧ください。

特定のコレクションをインポートする

エクスポートファイルのセットから特定のコレクショングループをインポートするには、--collection-ids フラグを使用します。この操作でインポートされるのは、指定したコレクション ID を持つコレクショングループのみです。コレクショングループには、指定したコレクション ID を持つすべてのコレクションとサブコレクション（任意のパス上）が含まれます。

特定のコレクショングループのインポートがサポートされるのは、特定のコレクショングループをエクスポートした場合のみです。すべてのドキュメントのエクスポートから特定のコレクションをインポートすることはできません。

gcloud beta firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]

エクスポート / インポートオペレーションの管理

エクスポートまたはインポートを開始すると、Cloud Firestore はそのオペレーションに一意の名前を割り当てます。このオペレーション名を使用して、オペレーションの削除、取り消し、状況確認を行うことができます。

次のように、オペレーション名の先頭には projects/[PROJECT_ID]/databases/(default)/operations/ という文字列が付きます。

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

ただし、describe、cancel、delete コマンドのオペレーション名を指定するときは、接頭辞を省略できます。

エクスポートとインポートのすべてのオペレーションを一覧表示する

実行中および最近完了したすべてのエクスポート / インポートオペレーションを表示するには、operations list コマンドを使用します。

gcloud beta firestore operations list

オペレーションの状態を確認する

エクスポート / インポートオペレーションのステータスを表示するには、operations describe コマンドを使用します。

gcloud beta firestore operations describe [OPERATION_NAME]

完了時間を予測する

長時間実行オペレーションのステータスをリクエストすると、workEstimated 指標と workCompleted 指標が返されます。これらの指標はバイト数とエンティティ数の両方で返されます。

workEstimated には、オペレーションで処理される推定の合計バイト数とドキュメント数が表示されます。
workCompleted には、これまでに処理されたバイト数とドキュメント数が表示されます。オペレーションが完了すると、実際に処理された合計バイト数とドキュメント数が表示されます。workEstimated の値よりも大きくなる可能性があります。

進行した割合を大まかに得るには、workCompleted を workEstimated で割ります。最新の統計情報コレクションとの間に遅延があるため、この割合は正確ではない可能性があります。

オペレーションのキャンセル

進行中のオペレーションを停止するには、operations cancel コマンドを使用します。

gcloud beta firestore operations cancel [OPERATION_NAME]

実行中のオペレーションを取り消しても、オペレーション前の状態には戻りません。エクスポートをキャンセルした場合は、エクスポート済みのドキュメントは Cloud Storage に残ります。また、インポートをキャンセルした場合はデータベースに行われた更新がそのまま残ります。部分的に完了したエクスポートはインポートできません。

オペレーションを削除する

operations list の出力からオペレーションを削除するには、operations delete コマンドを使用します。このコマンドは、Cloud Storage からエクスポートファイルを削除しません。

gcloud beta firestore operations delete [OPERATION_NAME]

エクスポート / インポートオペレーションの課金と料金

マネージドエクスポートおよびインポートサービスを使用する前に、Google Cloud Platform プロジェクトに対する課金を有効にする必要があります。エクスポート / インポートオペレーションでは、ドキュメントの読み取りと書き込み時に Cloud Firestore の料金が課金されます。

エクスポート / インポートオペレーションのコストは、費用制限の対象にはなりません。オペレーションが完了するまで、エクスポート / インポートオペレーションで Google Cloud Platform の予算アラートはトリガーされません。同様に、エクスポートまたはインポートオペレーションの実行中に行われる読み取りと書き込みは、オペレーションが完了してから 1 日の割り当てに適用されます。

BigQuery にエクスポート

Cloud Firestore のエクスポートから BigQuery にデータをロードできますが、collection-ids フィルタを指定した場合に限られます。Cloud Firestore のエクスポートからのデータの読み込みをご覧ください。