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

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

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

始める前に

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

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

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

各 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 Storage バケットの一連のファイルにコピーされます。エクスポートは、エクスポート開始時に取得された正確なデータベース スナップショットではありません。エクスポートには、オペレーションの実行中に追加された変更が含まれる場合があります。

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

Google Cloud Console

  1. Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。

    [インポート / エクスポート] ページに移動

  2. [エクスポート] をクリックします。

  3. [すべてのデータベースをエクスポートする] オプションをクリックします。

  4. [エクスポート先の選択] の下で、Cloud Storage バケットの名前を入力するか、または [参照] ボタンをクリックしてバケットを選択します。

  5. [エクスポート] をクリックします。

コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。

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

  1. Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。

    [インポート / エクスポート] ページに移動

  2. [エクスポート] をクリックします。

  3. [1 つまたは複数のコレクション グループをエクスポートする] オプションをクリックします。プルダウン メニューを使用して、1 つまたは複数のコレクション グループを選択します。

  4. [エクスポート先の選択] の下で、Cloud Storage バケットの名前を入力するか、または [参照] ボタンをクリックしてバケットを選択します。

  5. [エクスポート] をクリックします。

コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。

gcloud

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

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

データをインポートする

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

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

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

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

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

  • .overall_export_metadata ファイルの名前は親フォルダの名前と一致する必要があります。

    gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

    エクスポートの出力ファイルを移動またはコピーする場合は、PARENT_FOLDER_NAME.overall_export_metadata ファイルの名前を同じにしてください。

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

Google Cloud Console

  1. Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。

    [インポート / エクスポート] ページに移動

  2. [インポート] をクリックします。

  3. [ファイル名] フィールドに、完了したエクスポート オペレーションの .overall_export_metadata ファイルのファイル名を入力します。ファイルを選択する場合は、[参照] ボタンを使用します。

  4. [インポート] をクリックします。

コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。

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 ブラウザで確認できます。

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],[SUBCOLLECTION_ID_1]

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

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

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

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

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

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

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 には、オペレーションで処理される推定の合計バイト数とドキュメント数が表示されます。推定できない場合、Cloud Firestore はこの指標を省略することがあります。

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

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

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

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 レポートのページで、このラベルを使用します。

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

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

サービス エージェントの移行

App Engine サービス アカウントではなく Cloud Firestore サービス エージェントを使用して、インポート オペレーションとエクスポート オペレーションを承認できるようになりました。サービス エージェントとサービス アカウントでは、次の命名規則が使用されます。

Cloud Firestore サービス エージェント
service-project_number@gcp-sa-firestore.iam.gserviceaccount.com
App Engine サービス アカウント
project_id@appspot.gserviceaccount.com

Cloud Firestore サービス エージェントは Cloud Firestore 専用のものであるため、こちらをおすすめします。App Engine サービス アカウントは、複数のサービスで共有されます。

承認アカウントを表示する

インポート / エクスポート オペレーションでどのアカウントを使用してリクエストを承認するかは、Google Cloud Platform コンソールの [インポート / エクスポート] ページで確認できます。ここでデータベースが Cloud Firestore サービス エージェントをすでに使用しているかどうかも確認できます。

  1. Google Cloud Platform コンソールで Cloud Firestore の [インポート / エクスポート] ページに移動します。

    [インポート / エクスポート] に移動

  2. [インポート / エクスポート ジョブは…] のラベルに承認アカウントが表示されます。

プロジェクトで Cloud Firestore サービス エージェントを使用していない場合は、次のいずれかの方法で Cloud Firestore サービス エージェントに移行できます。

最初の方法は、単一の Cloud Firestore プロジェクトに効果の範囲をローカライズするため、こちらをおすすめします。次の方法は、既存の Cloud Storage バケットの権限を移行しないため、おすすめしません。ただし、組織レベルでのセキュリティのコンプライアンスは提供されます。

Cloud Storage バケットの権限を確認および更新して移行する

移行プロセスには、次の 2 つのステップがあります。

  1. Cloud Storage バケットの権限を更新する。詳細は、続くセクションで説明します。
  2. Cloud Firestore サービス エージェントへの移行を確認する。

サービス エージェント バケットの権限

別のプロジェクトの Cloud Storage バケットを使用するエクスポートまたはインポート オペレーションの場合は、そのバケットに対する Cloud Firestore サービス エージェント権限を付与する必要があります。たとえば、データを別のプロジェクトに移動するオペレーションでは、その別のプロジェクト内のバケットにアクセスする必要があります。権限がなければ、これらのオペレーションは Cloud Firestore サービス エージェントへの移行後に失敗します。

同じプロジェクト内に留まるインポートとエクスポートのワークフローでは、権限を変更する必要はありません。デフォルトでは、Cloud Firestore サービス エージェントは、同じプロジェクト内のバケットにアクセスできます。

他のプロジェクトの Cloud Storage バケットの権限を更新して、service-project_number@gcp-sa-firestore.iam.gserviceaccount.com サービス エージェントへのアクセスを許可します。サービス エージェントに Firestore Service Agent ロールを付与します。

Firestore Service Agent ロールでは、Cloud Storage バケットに対する読み取り権限と書き込み権限が付与されます。読み取り権限のみ、または書き込み権限のみを付与する必要がある場合は、カスタムロールを使用してください。

次のセクションで説明する移行プロセスは、権限の更新が必要になる Cloud Storage バケットの特定に役立ちます。

プロジェクトを Firestore サービス エージェントに移行する

App Engine サービス アカウントから Cloud Firestore サービス エージェントに移行するには、次の手順を行います。完了すると、移行は元に戻せません。

  1. Google Cloud Platform コンソールで Cloud Firestore の [インポート / エクスポート] ページに移動します。

    [インポート / エクスポート] に移動

  2. プロジェクトがまだ Firestore サービス エージェントに移行していない場合は、移行を説明するバナーと [バケットのステータスを確認] ボタンが表示されます。次の手順は、潜在的な権限エラーの特定と修正に役立ちます。

    [バケットのステータスを確認] をクリックします。

    移行を完了するためのオプションと、Cloud Storage バケットのリストが記載されたメニューが表示されます。リストの読み込みが終わるまで数分かかることがあります。

    このリストには、インポートとエクスポートのオペレーションで最近使用されたバケットが含まれていますが、Cloud Firestore サービス エージェントへの読み取りと書き込みの権限は付与されていません。

  3. プロジェクトの Cloud Firestore サービス エージェントのプリンシパル名をメモします。サービス エージェント名は、[アクセス権を付与するサービス エージェント] のラベルの下に表示されます。
  4. 今後のインポートまたはエクスポート オペレーションに使用するリスト内のバケットに対して、次の手順を行います。

    1. このバケットの表の行で [修正] をクリックします。そのバケットの権限ページが新しいタブで開きます。

    2. [追加] をクリックします。
    3. [新しいプリンシパル] フィールドに、Cloud Firestore サービス エージェントの名前を入力します。
    4. [ロールを選択] フィールドで、[サービス エージェント] > [Firestore サービス エージェント] の順に選択します。
    5. [保存] をクリックします。
    6. Cloud Firestore のインポート / エクスポート ページがあるタブに戻ります。
    7. リスト内の他のバケットについて、上記の手順を繰り返します。リストのすべてのページを表示してください。
  5. [Firestore サービス エージェントに移行] をクリックします。権限の確認に失敗したバケットがまだある場合は、[移行] をクリックして移行を確認する必要があります。

    移行が完了するとアラートが通知されます。移行は元に戻せません。

移行ステータスを表示する

  1. プロジェクトの移行ステータスを確認するには、Google Cloud Platform コンソールの [インポート / エクスポート] ページに移動します。

    [インポート / エクスポート] に移動

  2. [インポート / エクスポート ジョブは…] のラベルにあるプリンシパルを見つけます。

    プリンシパルが service-project_number@gcp-sa-firestore.iam.gserviceaccount.com の場合、プロジェクトはすでに Cloud Firestore サービス エージェントに移行されています。移行は元に戻せません。

    プロジェクトが移行されていない場合は、[バケットのステータスを確認] ボタンでページ上部にバナーが表示されます。移行を完了するには、Firestore サービス エージェントに移行するをご覧ください。

組織全体のポリシーの制約を追加する

  • 組織のポリシーに次の制約を設定します。

    インポート / エクスポート用に必要な Firestore サービス エージェントfirestore.requireP4SAforImportExport

    この制約により、インポートおよびエクスポート操作では、Cloud Firestore サービス エージェントを使用してリクエストを承認する必要があります。 この制約を設定するには、組織のポリシーの作成と管理をご覧ください。

この組織のポリシー制約を適用しても、Cloud Firestore サービス エージェントに適切な Cloud Storage バケット権限が自動的に付与されることはありません。

制約によってインポートまたはエクスポートのワークフローの権限エラーが発生した場合は、デフォルトのサービス アカウントを使用して制約を無効にし、元に戻せます。制約は、Cloud Storage バケットの権限を確認および更新すると再び有効にできます。