Cloud Firestore のマネージド エクスポート / インポート サービスを使用すると、誤って削除したデータを復元したり、オフライン処理用のデータをエクスポートしたりできます。すべてのドキュメントをエクスポートすることも、特定のコレクションだけをエクスポートすることもできます。同様に、エクスポートされたすべてのデータのインポートや、特定のコレクションのみのインポートも可能です。また、Cloud Firestore データベースからエクスポートされたデータを別の Cloud Firestore データベースにインポートすることもできます。Cloud Firestore のエクスポートを BigQuery に読み込むこともできます。
このページでは、マネージド エクスポート / インポート サービスと Cloud Storage を利用して、Cloud Firestore ドキュメントをエクスポートおよびインポートする方法について説明します。マネージド エクスポート / インポート サービスは、gcloud
コマンドライン ツールや Cloud Firestore API(REST、RPC)で利用できます。
始める前に
マネージド エクスポート / インポート サービスを使用するには、事前に次のタスクを完了する必要があります。
- Google Cloud プロジェクトに対する課金を有効にします。エクスポート機能とインポート機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。
- お使いの Cloud Firestore データベースのロケーションの近くにあるロケーションに、プロジェクトの Cloud Storage バケットを作成します。エクスポート / インポート オペレーションには、リクエスト元による支払いバケットは使用できません。
-
Cloud Firestore と Cloud Storage の操作に必要な権限がアカウントに付与されていることを確認します。プロジェクト オーナーであれば、アカウントに必要な権限が付与されています。それ以外の場合は、次のロールを指定して、エクスポート オペレーション、インポート オペレーション、Cloud Storage へのアクセスに必要な権限を付与できます。
- Cloud Firestore のロール:
Owner
、Cloud Datastore Owner
、またはCloud Datastore Import Export Admin
Cloud Storage のロール:
Owner
またはStorage Admin
- Cloud Firestore のロール:
デフォルトのサービス アカウント権限
各 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
にアクセスします。正しいプロジェクトに
gcloud
が構成されていることを確認します。gcloud config set project [PROJECT_ID]
データをエクスポートする
エクスポートを実行すると、データベース内のドキュメントが Cloud Storage バケットの一連のファイルにコピーされます。エクスポートは、エクスポート開始時に取得された正確なデータベース スナップショットではありません。エクスポートには、オペレーションの実行中に追加された変更が含まれる場合があります。
すべてのドキュメントをエクスポートする
Google Cloud Console
Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。
[エクスポート] をクリックします。
[すべてのデータベースをエクスポートする] オプションをクリックします。
[エクスポート先の選択] の下で、Cloud Storage バケットの名前を入力するか、または [参照] ボタンをクリックしてバケットを選択します。
[エクスポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。
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
Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。
[エクスポート] をクリックします。
[1 つまたは複数のコレクション グループをエクスポートする] オプションをクリックします。プルダウン メニューを使用して、1 つまたは複数のコレクション グループを選択します。
[エクスポート先の選択] の下で、Cloud Storage バケットの名前を入力するか、または [参照] ボタンをクリックしてバケットを選択します。
[エクスポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。
gcloud
特定のコレクション グループをエクスポートするには、--collection-ids
フラグを使用します。このオペレーションでエクスポートされるのは、指定したコレクション ID を持つコレクション グループのみです。コレクション グループには、指定したコレクション ID を持つすべてのコレクションとサブコレクション(任意のパス上)が含まれます。
gcloud firestore export gs://[BUCKET_NAME] --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]
データをインポートする
Cloud Storage にファイルをエクスポートすると、これらのファイルのドキュメントをプロジェクトまたは別のプロジェクトにインポートできます。インポートでは、次の点に注意してください。
データをインポートすると、データベースの現在のインデックス定義を使用して必要なインデックスが更新されます。エクスポートにインデックスの定義は含まれません。
インポートでは、新しいドキュメント ID が割り当てられません。インポートでは、エクスポート時に取得された ID を使用します。ドキュメントをインポートするときに、ドキュメントの ID が予約され、ID の競合が防止されます。同じ ID のドキュメントがすでに存在する場合、インポートを行うと既存のドキュメントが上書きされます。
データベース内のドキュメントがインポートの影響を受けない場合、そのドキュメントはインポート後もデータベースに維持されます。
インポート オペレーションによって Cloud Functions がトリガーされることはありません。スナップショット リスナーがインポート オペレーションに関連する更新を受け取ります。
エクスポートからすべてのドキュメントをインポートする
Google Cloud Console
Google Cloud Platform Console で Cloud Firestore の [インポート / エクスポート] ページに移動します。
[インポート] をクリックします。
[ファイル名] フィールドに、完了したエクスポート オペレーションの
.overall_export_metadata
ファイルのファイル名を入力します。ファイルを選択する場合は、[参照] ボタンを使用します。[インポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。オペレーションが正常に開始されると、最近のインポートとエクスポートのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。
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 ブラウザで確認できます。
インポート オペレーションを開始すると、ターミナルを閉じてもオペレーションはキャンセルされません。オペレーションのキャンセルをご覧ください。
特定のコレクションをインポートする
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]
エクスポート / インポート オペレーションの管理
エクスポートまたはインポートを開始すると、Cloud Firestore はそのオペレーションに一意の名前を割り当てます。このオペレーション名を使用して、オペレーションの削除、取り消し、ステータス確認を行うことができます。
次のように、オペレーション名の先頭には projects/[PROJECT_ID]/databases/(default)/operations/
という文字列が付きます。
projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
ただし、describe
、cancel
、delete
コマンドのオペレーション名を指定するときは、接頭辞を省略できます。
エクスポートとインポートのすべてのオペレーションを一覧表示する
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
には、オペレーションで処理される推定の合計バイト数とドキュメント数が表示されます。workCompleted
には、これまでに処理されたバイト数とドキュメント数が表示されます。オペレーションが完了すると、実際に処理された合計バイト数とドキュメント数が表示されます。workEstimated
の値よりも大きくなる可能性があります。
進行した割合を大まかに得るには、workCompleted
を workEstimated
で割ります。最新の統計情報コレクションとの間に遅延があるため、この割合は正確ではない可能性があります。
オペレーションのキャンセル
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 レポートのページで、このラベルを使用します。
監査ログ
Cloud Firestore は、Cloud Audit Logs の管理アクティビティ監査ログを書き込みます。管理アクティビティ監査ログには、エクスポート オペレーション、インポート オペレーション、インデックス登録オペレーションが含まれます。Cloud Firestore データベースの管理アクティビティ監査ログを表示するには、監査ログの表示をご覧ください。
Cloud Firestore 管理アクティビティ監査ログは、Cloud Datastore Database
と Cloud Datastore Index
のリソースタイプの下に表示されます。リソースタイプでは Cloud Datastore
名を使用しますが、個々のログエントリには Cloud Firestore の識別子が含まれます。Cloud Firestore では次のオペレーションがログに記録されます。
監査ログのカテゴリ | Cloud Firestore のオペレーション |
---|---|
管理アクティビティ | FirestoreAdmin.CreateIndex FirestoreAdmin.DeleteIndex FirestoreAdmin.ExportDocuments FirestoreAdmin.GetField FirestoreAdmin.GetIndex FirestoreAdmin.ImportDocuments FirestoreAdmin.ListFields FirestoreAdmin.ListIndexes FirestoreAdmin.UpdateField |
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 にデータを読み込めません。