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

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

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

始める前に

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

  1. Google Cloud Platform プロジェクトに対する課金を有効にします。エクスポートとインポートの機能を使用できるのは、課金が有効になっている GCP プロジェクトのみです。
  2. お使いの Cloud Firestore データベースのロケーションの近くにあるロケーションに、プロジェクトの Cloud Storage バケットを作成します。エクスポート / インポート オペレーションには、リクエスト元による支払いバケットは使用できません。

  3. Cloud Firestore と Cloud Storage の操作に必要な権限がアカウントに付与されていることを確認します。プロジェクト オーナーであれば、アカウントに必要な権限が付与されています。それ以外の場合は、次の役割を指定して、エクスポート オペレーション、インポート オペレーション、Cloud Storage へのアクセスに必要な権限を付与できます。

    • Cloud Firestore の役割: Owner、Cloud Datastore Owner、または Cloud Datastore Import Export Admin

    • Cloud Storage の役割: Owner または Storage Admin

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

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

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

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

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

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

gcloud firestore export gs://[BUCKET_NAME]

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

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

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

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

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

データをインポートする

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

  • データをインポートすると、データベースの現在のインデックス定義を使用して必要なインデックスが更新されます。エクスポートにインデックスの定義は含まれません。

  • インポートでは、新しいドキュメント ID が割り当てられません。インポートでは、エクスポート時に取得された ID を使用します。ドキュメントをインポートするときに、ドキュメントの ID が予約され、ID の競合が防止されます。同じ ID のドキュメントがすでに存在する場合、インポートを行うと既存のドキュメントが上書きされます。

  • データベース内のドキュメントがインポートの影響を受けない場合、そのドキュメントはインポート後もデータベースに維持されます。

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

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

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

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

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

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

Cloud Storage ブラウザを開く

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

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

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

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

gcloud 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 firestore operations list

オペレーションのステータスを確認する

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

gcloud firestore operations describe [OPERATION_NAME]

完了時間を予測する

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

  • workEstimated には、オペレーションで処理される推定の合計バイト数とドキュメント数が表示されます。

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

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

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

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

gcloud firestore operations cancel [OPERATION_NAME]

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

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

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

gcloud firestore operations delete [OPERATION_NAME]

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

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

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

BigQuery にエクスポート

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