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

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

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

始める前に

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

1. Google Cloud プロジェクトに対する課金を有効にします。エクスポート機能とインポート機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。
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

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

エクスポート オペレーションとインポート オペレーションでは、Cloud Firestore サービス エージェントを使用して Cloud Storage オペレーションを承認します。Cloud Firestore サービス エージェントは、次の命名規則を使用します。

Cloud Firestore サービス エージェント

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

サービス エージェントの詳細については、サービス エージェントをご覧ください。

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

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

サービス エージェントにロールを割り当てる

gsutil コマンドライン ツールを使用して、以下のいずれかのロールを割り当てることができます。たとえば、Storage Admin のロールを Cloud Firestore サービス エージェントに割り当てるには、次のコマンドを実行します。

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

PROJECT_NUMBER を Cloud Firestore サービス エージェント名に使用されているプロジェクト番号に置き換えます。サービス エージェント名を表示するには、サービス エージェント名を表示するをご覧ください。

Google Cloud コンソールを使用してこのロールを割り当てることもできます。

サービス エージェント名を表示する

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

1. [インポート / エクスポート ジョブの実行方法] ラベルの横にある承認アカウントを表示します。

エクスポートまたはインポート オペレーションには、サービス エージェントに Cloud Storage バケットに対する Storage Admin のロールが必要です。

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

インポートとエクスポートのオペレーションを開始するには、Google Cloud コンソールまたは gcloud コマンドライン ツールを使用します。gcloud を使用する場合は、次のいずれかの方法でコマンドライン ツールを設定し、プロジェクトに接続します。

• Cloud Shell を使用して、Google Cloud Platform コンソールから gcloud にアクセスします。

  Cloud Shell を起動する

  正しいプロジェクトに gcloud が構成されていることを確認します。

  gcloud config set project [PROJECT_ID]
  

• Google Cloud SDK をインストールして初期化します。

データのエクスポート

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

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

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

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

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

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

PITR タイムスタンプからエクスポートする

gcloud firestore export コマンドを使用すると、PITR データから Cloud Storage にデータベースをエクスポートできます。タイムスタンプが過去 7 日以内（ただし earliestVersionTime 以降）の 1 分単位の場合は、PITR データをエクスポートできます。指定したタイムスタンプにデータがもう存在しない場合、エクスポート オペレーションは失敗します。

PITR エクスポート オペレーションでは、すべてのドキュメントのエクスポート、特定のコレクションのエクスポートなど、すべてのフィルタがサポートされています。

1. snapshot-time パラメータを目的のリカバリ タイムスタンプに指定して、データベースをエクスポートします。

   gcloud

   次のコマンドを実行して、データベースをバケットにエクスポートします。

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   ここで

   • PITR_TIMESTAMP - 分単位の PITR タイムスタンプ（例: 2023-05-26T10:20:00.00Z）。

   PITR データをエクスポートする前に、次の点に注意してください。

   • RFC 3339 形式でタイムスタンプを指定しますたとえば、2020-09-01T23:59:30.234233Z です。
   • タイムスタンプは、過去 7 日間以内（ただし earliestVersionTime 以降）の 1 分単位のタイムスタンプを指定する必要があります。指定したタイムスタンプにデータが存在しない場合、エラーが発生します。
   • 失敗した PITR エクスポートについては課金されません。

データのインポート

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 ファイルの名前を同じにしてください。

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

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

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

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
  --database=[DATABASE]

PITR エクスポートをインポートする

すべてのドキュメントをインポートする手順に沿って、エクスポートしたデータベースをインポートします。データベースにすでにドキュメントが存在する場合は上書きされます。

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

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

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

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

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

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

gcloud firestore operations list

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

gcloud firestore operations describe [OPERATION_NAME]

完了時間を予測する

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

• workEstimated には、オペレーションで処理される推定の合計バイト数とドキュメント数が表示されます。推定できない場合、Cloud Firestore はこの指標を省略する可能性があります。

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

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

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

gcloud firestore operations cancel [OPERATION_NAME]

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

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

最近のオペレーションのリストからオペレーションを削除するには、gcloud firestore operations delete コマンドを使用します。このコマンドで Cloud Storage からエクスポート ファイルが削除されることはありません。

gcloud firestore operations delete [OPERATION_NAME]

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

マネージド エクスポートおよびインポート サービスを使用する前に、Google Cloud プロジェクトに対する課金を有効にする必要があります。

エクスポート / インポート オペレーションでは、ドキュメントの読み取りと書き込み時に Cloud Firestore の料金が課金されます。エクスポート オペレーションでは、エクスポートされるドキュメントごとに 1 回の読み取りオペレーションが発生します。インポート オペレーションでは、インポートされるドキュメントごとに 1 回の書き込みオペレーションが発生します。

Cloud Storage に保存された出力ファイルは、Cloud Storage のデータ ストレージ コストにカウントされます。

エクスポート / インポート オペレーションのコストは、費用制限の対象にはなりません。オペレーションが完了するまで、エクスポート / インポート オペレーションで 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

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

Cloud Firestore は、App Engine サービス アカウントを使用する代わりに、Cloud Firestore サービス エージェントを使用してインポートとエクスポートのオペレーションを承認します。サービス エージェントとサービス アカウントは、次の命名規則を使用します。

Cloud Firestore サービス エージェント

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Cloud Firestore では、以前は Cloud Firestore サービス エージェントの代わりに App Engine のデフォルトのサービス アカウントを使用していました。データベースが依然として App Engine サービス アカウントを使用してデータをインポートまたはエクスポートしている場合は、このセクションの手順に沿って Cloud Firestore サービス エージェントの使用に移行することをおすすめします。

App Engine サービス アカウント

PROJECT_ID@appspot.gserviceaccount.com

Cloud Firestore サービス エージェントは、Cloud Firestore に固有であるため、おすすめです。App Engine サービス アカウントは、複数のサービスで共有されます。

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

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

1. Google Cloud コンソールで [データベース] ページに移動します。

   [データベース] に移動

2. データベースのリストから、必要なデータベースを選択します。

3. ナビゲーション メニューで [インポート / エクスポート] をクリックします。

4. [インポート / エクスポート ジョブの実行方法] ラベルの横にある承認アカウントを表示します。

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

• Cloud Storage バケットの権限を確認して更新することで、プロジェクトを移行する（推奨）。
• 組織内のすべてのプロジェクトに影響を与える組織全体のポリシーの制約を追加する。

最初の方法は、単一の Cloud Firestore プロジェクトに効果の範囲をローカライズするため、こちらをおすすめします。2 番目の方法は、既存の 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 コンソールで [データベース] ページに移動します。

   [データベース] に移動

2. データベースのリストから、必要なデータベースを選択します。

3. ナビゲーション メニューで [インポート / エクスポート] をクリックします。

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

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

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

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

5. プロジェクトの Cloud Firestore サービス エージェントのプリンシパル名をメモします。サービス エージェント名は、[アクセス権を付与するサービス エージェント] ラベルの下に表示されます。

6. 今後のインポートまたはエクスポート オペレーションに使用するリスト内のバケットに対して、次の手順を行います。

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

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

7. [Firestore サービス エージェントに移行] をクリックします。権限の確認に失敗したバケットがまだある場合は、[移行] をクリックして移行を確認する必要があります。

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

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

プロジェクトの移行ステータスを確認するには:

1. Google Cloud コンソールで [データベース] ページに移動します。

   [データベース] に移動

2. データベースのリストから、必要なデータベースを選択します。

3. ナビゲーション メニューで [インポート / エクスポート] をクリックします。

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

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

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

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

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

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

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

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

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