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

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

このページでは、マネージド エクスポート / インポート サービスと Cloud Storage を利用して、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

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

各 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 Shell を使用して、Google Cloud Platform Console から gcloud にアクセスします。

  Cloud Shell の起動

  正しいプロジェクトに 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]

データをインポートする

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

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

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

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

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

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

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]

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

エクスポートまたはインポートを開始すると、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 には、オペレーションで処理される推定の合計バイト数とドキュメント数が表示されます。

• 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 にエクスポートする

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