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

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

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

注意: Cloud Firestore からデータをエクスポートすると、エクスポートされるドキュメントごとに 1 回の読み取りオペレーションが発生します。しかし、この読み取りはコンソールの使用状況セクションに表示されません。定期的なエクスポートを設定する前には、予想外の請求を回避するために、必ずこのことを理解しておいてください。

始める前に

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

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

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

   • Cloud Firestore のロール: Owner、Cloud Datastore Owner、または Cloud Datastore Import Export Admin
     注: これらの Datastore のロールは、Cloud Firestore にも権限を付与します。

   • Cloud Storage のロール: Owner または Storage Admin

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

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

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

[e-mail]

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

注: Cloud Firestore では、以前は Cloud Firestore サービス エージェントの代わりに App Engine のデフォルトのサービス アカウントを使用していました。データベースが依然として App Engine サービス アカウントを使用してデータをインポートまたはエクスポートしている場合は、サービス固有の Cloud Firestore サービス エージェントに移行することをおすすめします。Google Cloud Platform コンソールで、インポートとエクスポートのオペレーションで使用するアカウントを確認できます。

VPC Service Controls を使用する場合は、サービス固有の Cloud Firestore サービス エージェントを使用して、インポートとエクスポートのオペレーションを完全に保護する必要があります。VPC Service Controls は App Engine サービス アカウントと互換性がありません。

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:[e-mail]:roles/storage.admin \
    gs://[BUCKET_NAME]

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

別の方法として、GCP Console を使用してこの役割を割り当てることもできます。

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

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

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

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

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

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

• Cloud Shell を使用して、Google Cloud Platform Console から gcloud にアクセスします。

  Cloud Shell の起動

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

  gcloud config set project [PROJECT_ID]
  

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

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

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

注: 以下を行う予定の場合は、特定のコレクションをエクスポートする必要があります。

• 特定のコレクションのみをインポートする
• BigQuery に Cloud Firestore データを読み込む

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

Google Cloud Console

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

   [データベース] に移動

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

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

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

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

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

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

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

gcloud

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

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

以下を置き換えます。

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

• DATABASE: ドキュメントのエクスポート元のデータベースの名前。デフォルト データベースの場合は、--database='(default)' を使用します。

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

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

Google Cloud Console

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

   [データベース] に移動

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

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

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

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

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

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

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

gcloud

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

注: コレクションをエクスポートしても、そのサブコレクションは自動的にエクスポートされません。エクスポートするサブコレクションも指定する必要があります。

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

たとえば、ratings、reviews、outlets などの複数のサブコレクションを含めるように foo データベースで restaurants コレクションを設計できます。特定のコレクション restaurants と reviews をエクスポートする場合、コマンドは次のようになります。

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

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

Google Cloud Console

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

   [データベース] に移動

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

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

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

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

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

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

gcloud

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

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

以下を置き換えます。

• BUCKET_NAME/EXPORT_PREFIX: エクスポート ファイルの場所。

• DATABASE: データベースの名前。デフォルト データベースの場合は、--database='(default)' を使用します。

次に例を示します。

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

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

Cloud Storage ブラウザを開く

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

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

注: 特定のコレクションをインポートするには、特定のコレクションをエクスポートしたエクスポート オペレーションの出力を使用する必要があります。

Google Cloud コンソール

コンソールでは、特定のコレクションを選択できません。gcloud を代わりに使用してください。

gcloud

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

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

  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 コマンドのオペレーション名を指定するときは、接頭辞を省略できます。

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

Google Cloud Console

Google Cloud Platform コンソールの [インポート / エクスポート] ページで、最近のエクスポートとインポートのオペレーションの一覧を確認できます。

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

   [データベース] に移動

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

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

gcloud

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

gcloud firestore operations list

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

Google Cloud Console

Google Cloud Platform コンソールの [インポート / エクスポート] ページで、最近のエクスポートとインポートのオペレーションのステータスを確認できます。

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

   [データベース] に移動

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

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

gcloud

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

gcloud firestore operations describe [OPERATION_NAME]

完了時間を予測する

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

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

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

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

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

Google Cloud Console

Google Cloud Platform コンソールの [インポート / エクスポート] ページで、実行中のエクスポートまたはインポートのオペレーションをキャンセルできます。

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

   [データベース] に移動

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

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

[最近のインポートとエクスポート] の表で、現在実行中のオペレーションの [完了] の列に [キャンセル] ボタンが表示されます。[キャンセル] ボタンをクリックして、オペレーションを停止します。ボタンが [キャンセル中] に変わり、オペレーションが完全に停止すると [キャンセル済み] に変わります。

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 の料金が課金されます。エクスポート オペレーションでは、エクスポートされるドキュメントごとに 1 回の読み取りオペレーションが発生します。インポート オペレーションでは、インポートされるドキュメントごとに 1 回の書き込みオペレーションが発生します。

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

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

エクスポートとインポートの費用を確認する

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

注: 2020 年 9 月 8 日より前に実行されたエクスポートとインポートのオペレーションでは、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

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

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

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

[e-mail]

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

App Engine サービス アカウント

[e-mail]

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

注: VPC Service Controls を使用する場合は、Cloud Firestore サービス エージェントを使用して、インポートとエクスポートのオペレーションを完全に保護する必要があります。VPC Service Controls は App Engine サービス アカウントと互換性がありません。

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

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

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

   [データベース] に移動

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

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

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

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

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

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

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

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

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

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

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

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

他のプロジェクトの Cloud Storage バケットの権限を更新して、[e-mail] サービス エージェントへのアクセスを許可します。サービス エージェントに Firestore Service Agent ロールを付与します。

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

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

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

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

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

   [データベース] に移動

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

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

4. プロジェクトがまだ 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 Platform コンソールで、[データベース] ページに移動します。

   [データベース] に移動

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

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

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

   プリンシパルが [e-mail] の場合、プロジェクトはすでに Cloud Firestore サービス エージェントに移行されています。移行は元に戻せません。

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

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

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

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

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

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

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