Cloud Firestore のマネージド エクスポート / インポート サービスを使用すると、誤って削除したデータを復元したり、オフライン処理用のデータをエクスポートしたりできます。すべてのドキュメントをエクスポートすることも、特定のコレクションだけをエクスポートすることもできます。同様に、エクスポートされたすべてのデータのインポートや、特定のコレクションのみのインポートも可能です。また、Cloud Firestore データベースからエクスポートされたデータを別の Cloud Firestore データベースにインポートすることもできます。Cloud Firestore のエクスポートを BigQuery に読み込むこともできます。
このページでは、マネージド エクスポート / インポート サービスと Cloud Storage を利用して、Cloud Firestore ドキュメントをエクスポートおよびインポートする方法について説明します。マネージド エクスポート / インポート サービスは、gcloud コマンドライン ツールや Cloud Firestore API（REST、RPC）で利用できます。
始める前に
マネージド エクスポート / インポート サービスを使用するには、事前に次のタスクを完了する必要があります。
- Google Cloud プロジェクトに対する課金を有効にします。エクスポート機能とインポート機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。
- お使いの Cloud Firestore データベースのロケーションの近くにあるロケーションに、プロジェクトの Cloud Storage バケットを作成します。エクスポート / インポート オペレーションには、リクエスト元による支払いバケットは使用できません。
-
Cloud Firestore と Cloud Storage の操作に必要な権限がアカウントに付与されていることを確認します。プロジェクト オーナーであれば、アカウントに必要な権限が付与されています。それ以外の場合は、次のロールを指定して、エクスポート オペレーション、インポート オペレーション、Cloud Storage へのアクセスに必要な権限を付与できます。
- Cloud Firestore のロール:
Owner、Cloud Datastore Owner、またはCloud Datastore Import Export Admin Cloud Storage のロール:
OwnerまたはStorage Admin
- Cloud Firestore のロール:
デフォルトのサービス アカウント権限
各 Google Cloud プロジェクトには、PROJECT_ID@appspot.gserviceaccount.com という名前のデフォルトのサービス アカウントが自動的に作成されています。エクスポートおよびインポート オペレーションでは、このサービス アカウントを使用して Cloud Storage オペレーションを承認します。
プロジェクトのデフォルトのサービス アカウントには、エクスポートまたはインポート オペレーションで使用される Cloud Storage バケットへのアクセス権限が必要です。Cloud Storage バケットが Cloud Firestore データベースと同じプロジェクトにある場合、デフォルトのサービス アカウントには、デフォルトでそのバケットへのアクセス権限があります。
Cloud Storage バケットが別のプロジェクトにある場合は、デフォルトのサービス アカウントに Cloud Storage バケットへのアクセス権限を付与する必要があります。
Cloud Storage バケットをエクスポートまたはインポートのオペレーションに使用するには、サービス アカウントに Storage Admin ロールが必要です。
App Engine のデフォルトのサービス アカウントを無効にするか削除すると、App Engine アプリから Cloud Firestore データベースへのアクセス権限が失われます。App Engine のサービス アカウントを無効化しても、再び有効化できます。サービス アカウントの有効化をご覧ください。App Engine のサービス アカウントを削除しても、その削除が過去 30 日以内であればサービス アカウントを復元できます。サービス アカウントの削除の取り消しをご覧ください。
プロジェクトの gcloud を設定する
インポートとエクスポートのオペレーションを開始するには、Google Cloud Platform Console または gcloud コマンドライン ツールを使用します。gcloud を使用する場合は、次のいずれかの方法でコマンドライン ツールを設定し、プロジェクトに接続します。
Cloud Shell を使用して、Google Cloud Platform Console から
gcloudにアクセスします。正しいプロジェクトに
gcloudが構成されていることを確認します。gcloud config set project [PROJECT_ID]
データをエクスポートする
エクスポートを実行すると、データベース内のドキュメントが Cloud Storage バケットの一連のファイルにコピーされます。エクスポートは、エクスポート開始時に取得された正確なデータベース スナップショットではありません。エクスポートには、オペレーションの実行中に追加された変更が含まれる場合があります。
すべてのドキュメントをエクスポートする
Google Cloud Console
Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。
[エクスポート] をクリックします。
[すべてのデータベースをエクスポートする] オプションをクリックします。
[移行先] の下で、Cloud Storage バケットの名前を入力するか、または [BROWSE] ボタンをクリックしてバケットを選択します。
[エクスポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。
gcloud
firestore export コマンドを使用してデータベース内のすべてのドキュメントをエクスポートします。[BUCKET_NAME] は Cloud Storage バケットの名前に置き換えてください。--async フラグを追加すると、gcloud ツールはオペレーションの完了を待機しません。
gcloud firestore export gs://[BUCKET_NAME]
バケット名の後にファイル接頭辞（たとえば、BUCKET_NAME/my-exports-folder/export-name）を追加すると、エクスポートを整理できます。ファイル接頭辞を指定しない場合、マネージド エクスポート サービスは現在のタイムスタンプに基づいてエクスポートを作成します。
エクスポートを開始すると、ターミナルを閉じても処理はキャンセルされません。オペレーションのキャンセルをご覧ください。
特定のコレクションをエクスポートする
Google Cloud Console
Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。
[エクスポート] をクリックします。
[1 つまたは複数のコレクション グループをエクスポートする] オプションをクリックします。プルダウン メニューを使用して、1 つまたは複数のコレクション グループを選択します。
[移行先] の下で、Cloud Storage バケットの名前を入力するか、または [BROWSE] ボタンをクリックしてバケットを選択します。
[エクスポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。
gcloud
特定のコレクション グループをエクスポートするには、--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 のドキュメントがすでに存在する場合、インポートを行うと既存のドキュメントが上書きされます。
データベース内のドキュメントがインポートの影響を受けない場合、そのドキュメントはインポート後もデータベースに維持されます。
インポート オペレーションによって Cloud Functions がトリガーされることはありません。スナップショット リスナーがインポート オペレーションに関連する更新を受け取ります。
エクスポートからすべてのドキュメントをインポートする
Google Cloud Console
Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。
[インポート] をクリックします。
[ファイル名] フィールドに、完了したエクスポート オペレーションの
.overall_export_metadataファイルのファイル名を入力します。ファイルを選択する場合は、[BROWSE] ボタンを使用します。[インポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。
gcloud
以前のエクスポート オペレーションからドキュメントをインポートするには、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 ブラウザで確認できます。
インポート オペレーションを開始すると、ターミナルを閉じてもオペレーションはキャンセルされません。オペレーションのキャンセルをご覧ください。
特定のコレクションをインポートする
Google Cloud Console
コンソールでは、特定のコレクションを選択できません。gcloud を代わりに使用してください。
gcloud
エクスポート ファイルのセットから特定のコレクション グループをインポートするには、--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 コマンドのオペレーション名を指定するときは、接頭辞を省略できます。
エクスポートとインポートのすべてのオペレーションを一覧表示する
Google Cloud Console
Google Cloud Platform Console では、Cloud Firestore の [インポート / エクスポート] ページで、最近のエクスポートとインポートのオペレーションの一覧を表示できます。
gcloud
実行中および最近完了したすべてのエクスポート / インポート オペレーションを表示するには、operations list コマンドを使用します。
gcloud firestore operations list
オペレーションのステータスを確認する
Google Cloud Console
Google Cloud Platform Console では、Cloud Firestore の [インポート / エクスポート] ページで、最近のエクスポートまたはインポートのオペレーションのステータスを確認できます。
gcloud
エクスポートまたはインポート オペレーションのステータスを表示するには、operations describe コマンドを実行します。
gcloud firestore operations describe [OPERATION_NAME]
完了時間を予測する
長時間実行オペレーションのステータスをリクエストすると、workEstimated 指標と workCompleted 指標が返されます。これらの指標はバイト数とエンティティ数の両方で返されます。
workEstimatedには、オペレーションで処理される推定の合計バイト数とドキュメント数が表示されます。workCompletedには、これまでに処理されたバイト数とドキュメント数が表示されます。オペレーションが完了すると、実際に処理された合計バイト数とドキュメント数が表示されます。workEstimatedの値よりも大きくなる可能性があります。
進行した割合を大まかに得るには、workCompleted を workEstimated で割ります。最新の統計情報コレクションとの間に遅延があるため、この割合は正確ではない可能性があります。
オペレーションのキャンセル
Google Cloud Console
Google Cloud Platform Console では、Cloud Firestore の [インポート / エクスポート] ページで、実行中のエクスポートまたはインポートのオペレーションをキャンセルできます。
[最近のインポートとエクスポート] の表で、現在実行中のオペレーションの [完了] の列に [キャンセル] ボタンが表示されます。[キャンセル] ボタンをクリックして、オペレーションを停止します。ボタンが [キャンセル中] に変わり、オペレーションが完全に停止すると [キャンセル済み] に変わります。
gcloud
進行中のオペレーションを停止するには、operations cancel コマンドを使用します。
gcloud firestore operations cancel [OPERATION_NAME]
実行中のオペレーションを取り消しても、オペレーション前の状態には戻りません。エクスポートをキャンセルした場合は、エクスポート済みのドキュメントは Cloud Storage に残ります。また、インポートをキャンセルした場合はデータベースに行われた更新がそのまま残ります。部分的に完了したエクスポートはインポートできません。
オペレーションを削除する
最近のオペレーションのリストからオペレーションを削除するには、gcloud firestore operations delete コマンドを使用します。このコマンドで Cloud Storage からエクスポート ファイルが削除されることはありません。
gcloud firestore operations delete [OPERATION_NAME]
エクスポート / インポート オペレーションの課金と料金
マネージド エクスポートおよびインポート サービスを使用する前に、Google Cloud プロジェクトに対する課金を有効にする必要があります。エクスポート / インポート オペレーションでは、ドキュメントの読み取りと書き込み時に Cloud Firestore の料金が課金されます。
エクスポート / インポート オペレーションのコストは、費用制限の対象にはなりません。オペレーションが完了するまで、エクスポート / インポート オペレーションで Google Cloud の予算アラートはトリガーされません。同様に、エクスポートまたはインポートのオペレーションの実行中に行われる読み取りと書き込みは、オペレーションが完了してから 1 日の割り当てに適用されます。エクスポートとインポートのオペレーションは、コンソールの使用状況セクションに表示される使用量には反映されません。
エクスポートとインポートの費用を確認する
課金対象のオペレーションには、エクスポートとインポートのオペレーションにより goog-firestoremanaged:exportimport ラベルが適用されます。エクスポートとインポートのオペレーションに関連する費用を表示するには、Cloud Billing レポートのページで、このラベルを使用します。
BigQuery にエクスポートする
Cloud Firestore のエクスポートから BigQuery にデータを読み込めますが、collection-ids フィルタを指定した場合に限られます。Cloud Firestore のエクスポートからのデータの読み込みをご覧ください。
BigQuery の列の上限
BigQuery では、テーブルあたりの列の数が 10,000 に制限されています。Cloud Firestore のエクスポート オペレーションでは、コレクション グループごとに BigQuery テーブル スキーマが生成されます。このスキーマでは、コレクション グループに含まれる一意のフィールド名のそれぞれがスキーマの列になります。
コレクション グループの BigQuery スキーマの列数が 10,000 列を超える場合、Cloud Firestore のエクスポート オペレーションでは列数の上限内に収まるように、マップ フィールドをバイトとして扱います。この変換によって列数が 10,000 を下回れば、データを BigQuery に読み込むことができますが、マップ フィールド内のサブフィールドのクエリは行えません。列数がそれでも 10,000 を下回らない場合は、エクスポート オペレーションによってコレクション グループの BigQuery スキーマは生成されず、BigQuery にデータを読み込めません。
エクスポート形式とメタデータ ファイル
マネージド エクスポートの出力では、LevelDB ログ形式が使用されます。
メタデータ ファイル
エクスポート オペレーションでは、指定したコレクション グループごとにメタデータ ファイルが作成されます。通常、メタデータ ファイルの名前は ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata です。
メタデータ ファイルはプロトコル バッファであり、protoc プロトコル コンパイラでデコードできます。たとえば、次のように、メタデータ ファイルをデコードして、エクスポート ファイルに含まれるコレクション グループを判別できます。
protoc --decode_raw < export0.export_metadata