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

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

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

始める前に

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

  1. Google Cloud プロジェクトに対する課金を有効にします。エクスポート機能とインポート機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。
  2. お使いの Firestore データベースの場所に近いロケーションに、プロジェクトの Cloud Storage バケットを作成します。エクスポート / インポート オペレーションには、リクエスト元による支払いバケットは使用できません。
  3. Firestore と Cloud Storage の操作に必要な権限がアカウントに付与されていることを確認します。プロジェクト オーナーであれば、アカウントに必要な権限が付与されています。それ以外の場合は、次の役割を指定して、エクスポート オペレーション、インポート オペレーション、Cloud Storage へのアクセスに必要な権限を付与できます。

    • Firestore のロール: OwnerCloud Datastore Owner、または Cloud Datastore Import Export Admin
    • Cloud Storage の役割: Owner または Storage Admin

デフォルトのサービス アカウント権限

各 Google Cloud プロジェクトには、PROJECT_ID@appspot.gserviceaccount.com という名前のデフォルトのサービス アカウントが自動的に作成されています。エクスポートおよびインポート オペレーションでは、このサービス アカウントを使用して Cloud Storage オペレーションを承認します。

プロジェクトのデフォルトのサービス アカウントには、エクスポートまたはインポート オペレーションで使用される Cloud Storage バケットへのアクセス権限が必要です。Cloud Storage バケットが Firestore データベースと同じプロジェクトにある場合は、最初からデフォルトのサービス アカウントでバケットにアクセスできます

Cloud Storage バケットが別のプロジェクトにある場合は、デフォルトのサービス アカウントに Cloud Storage バケットへのアクセス権限を付与する必要があります。

エクスポートまたはインポート オペレーションには、サービス アカウントに Cloud Storage バケットに対する Storage Admin の役割が必要です。

App Engine のデフォルトのサービス アカウントを無効にするか削除すると、App Engine アプリから Firestore データベースにアクセスできなくなります。App Engine のサービス アカウントを無効にした場合は、再度有効にできます。サービス アカウントの有効化をご覧ください。過去 30 日以内に App Engine サービス アカウントを削除した場合は、サービス アカウントを復元できます。サービス アカウントの削除の取り消しをご覧ください。

プロジェクトの 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 のドキュメントがすでに存在する場合、インポートを行うと既存のドキュメントが上書きされます。

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

  • インポート オペレーションによって Cloud Functions はトリガーされません。スナップショット リスナーは、インポート オペレーションに関連する更新を受け取ります。

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

以前のエクスポートからドキュメントをインポートするには、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 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]

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

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

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

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

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

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

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

gcloud firestore operations list

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

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

gcloud firestore operations describe [OPERATION_NAME]

完了時間を予測する

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

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

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

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

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

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

gcloud firestore operations cancel [OPERATION_NAME]

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

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

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

gcloud firestore operations delete [OPERATION_NAME]

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

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

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

エクスポートとインポートの料金を確認する

エクスポート / インポート オペレーションでは、課金対象のオペレーションに goog-firestoremanaged:exportimport ラベルが適用されます。Cloud Billing レポートページでは、このラベルを使用して、エクスポート / インポート オペレーションに関連する料金を表示できます。

フィルタ メニューから goog-firestoremanaged ラベルにアクセスします。

監査ログ

Firestore は、Cloud Audit Logs の管理アクティビティ監査ログを書き込みます。管理アクティビティ監査ログには、エクスポート オペレーション、インポート オペレーション、インデックス登録オペレーションが記録されます。Firestore データベースの管理アクティビティ監査ログを表示するには、監査ログの表示をご覧ください。

Firestore 管理アクティビティ監査ログは、Cloud Datastore DatabaseCloud Datastore Index のリソースタイプの下に表示されます。リソースタイプでは Cloud Datastore 名を使用しますが、個々のログエントリには Firestore の識別子が含まれます。Firestore は次のオペレーションをログに記録します。

監査ログのカテゴリ Firestore のオペレーション
管理アクティビティ FirestoreAdmin.CreateIndex
FirestoreAdmin.DeleteIndex
FirestoreAdmin.ExportDocuments
FirestoreAdmin.GetField
FirestoreAdmin.GetIndex
FirestoreAdmin.ImportDocuments
FirestoreAdmin.ListFields
FirestoreAdmin.ListIndexes
FirestoreAdmin.UpdateField

BigQuery にエクスポートする

Firestore のエクスポートから BigQuery にデータを読み込むことができるのは、collection-ids フィルタを指定した場合のみです。Firestore エクスポートからのデータの読み込みをご覧ください。

BigQuery の列の上限

BigQuery では、テーブルあたりの列の数が 10,000 に制限されています。Firestore のエクスポート オペレーションでは、コレクション グループごとに BigQuery テーブル スキーマが生成されます。このスキーマでは、コレクション グループに含まれる一意のフィールド名のそれぞれがスキーマの列になります。

コレクション グループの BigQuery スキーマの列数が 10,000 列を超える場合、Firestore のエクスポート オペレーションでは列数の上限内に収まるように、マップ フィールドをバイトとして扱います。この変換によって列数が 10,000 を下回れば、データを BigQuery に読み込むことができますが、マップ フィールド内のサブフィールドのクエリは行えません。列数がそれでも 10,000 を下回らない場合は、エクスポート オペレーションによってコレクション グループの BigQuery スキーマは生成されず、BigQuery にデータを読み込めません。