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

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 Storage バケットを、 Cloud Firestore データベースの場所の近くに作成します。リクエスタ支払いバケットをエクスポートおよびインポート操作に使用することはできません。

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

   • Cloud Firestore の役割: Owner 、 Cloud 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 バケットが Cloud Firestore データベースと同じプロジェクトにある場合、デフォルトのサービス アカウントはデフォルトでバケットにアクセスできます。

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

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

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

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

Google Cloud Platform Console またはgcloudコマンドライン ツールを使用して、インポートおよびエクスポート操作を開始できます。 gcloudを使用するには、コマンドライン ツールを設定し、次のいずれかの方法でプロジェクトに接続します。

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

  クラウド シェルを開始する

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

  gcloud config set project [PROJECT_ID]
  

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

データのエクスポート

エクスポート オペレーションは、データベース内のドキュメントを Cloud Storage バケット内の一連のファイルにコピーします。エクスポートは、エクスポート開始時に作成された正確なデータベース スナップショットではないことに注意してください。エクスポートには、操作の実行中に行われた変更が含まれる場合があります。

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

gcloud firestore export gs://[BUCKET_NAME]

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

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ファイル名を同じにします。

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

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

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

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

ただし、 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の料金表に記載されている料金で課金されます。

エクスポートおよびインポート操作のコストは、使用制限にはカウントされません。エクスポートまたはインポート オペレーションは、完了するまでGoogle Cloud 予算アラートをトリガーしません。同様に、エクスポートまたはインポート操作中に実行された読み取りと書き込みは、操作の完了後に1 日のクォータに適用されます。エクスポートおよびインポート操作は、コンソールの使用セクションに表示される使用には影響しません。

輸出入コストの表示

エクスポート操作とインポート操作は、 goog-firestoremanaged:exportimportラベルを請求対象の操作に適用します。 Cloud Billing レポート ページでは、このラベルを使用して、インポートおよびエクスポート オペレーションに関連する費用を表示できます。

BigQuery にエクスポート

collection-idsフィルタを指定した場合に限り、Cloud Firestore エクスポートから BigQuery にデータを読み込むことができます。 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 Console の [インポート/エクスポート]ページから、インポート操作とエクスポート操作でリクエストを承認するために使用するアカウントを確認できます。データベースがすでに Cloud Firestore サービス エージェントを使用しているかどうかを確認することもできます。

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

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

2. Import/Export jobs run asラベルの横にある承認アカウントを表示します。

プロジェクトで 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 Platform Console のCloud Firestore インポート/エクスポートページに移動します。

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

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

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

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

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

3. プロジェクトの Cloud Firestore サービス エージェントのプリンシパル名をメモします。サービス エージェント名は、サービス エージェントの下に表示され、ラベルへのアクセスを提供します。

4. 今後のインポートまたはエクスポート操作に使用するリスト内のバケットについて、次の手順を実行します。

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

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

5. [ Migrate to Firestore Service Agent] をクリックします。権限チェックに失敗したバケットがまだある場合は、[移行] をクリックして移行を確認する必要があります。

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

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

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

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

2. Import/Export jobs run asラベルの横にあるプリンシパルを探します。

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

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

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

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

  インポート/エクスポートには Firestore サービス エージェントが必要です ( firestore.requireP4SAforImportExport )。

  この制約では、Cloud Firestore サービス エージェントを使用してリクエストを承認するためのインポート操作とエクスポート操作が必要です。この制約を設定するには、「組織のポリシーの作成と管理」を参照してください。

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

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