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

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

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

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

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

始める前に

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

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

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

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

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

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

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

Firestore サービス エージェント

[e-mail]

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

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

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

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

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

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

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

gsutil iam ch serviceAccount:[e-mail]:roles/storage.admin \
    gs://[BUCKET_NAME]

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

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

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

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

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

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

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

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

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

  Cloud Shell の起動

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

  gcloud config set project [PROJECT_ID]
  

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

データのインポート

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

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

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

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

• .overall_export_metadata ファイルの名前は親フォルダの名前と一致する必要があります。

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

  エクスポートの出力ファイルを移動またはコピーする場合は、PARENT_FOLDER_NAME と .overall_export_metadata ファイルの名前を同じにしてください。

• サブコレクションは MongoDB 互換の Firestore でサポートされていないため、サブコレクションを含むエクスポートから MongoDB 互換の Firestore データベースへのインポートは失敗します。

• Firestore Standard エディションでは BSON 型がサポートされていないため、BSON 型を含むエクスポートから Firestore Standard エディション データベースへのインポートは失敗します。

• MongoDB 互換の Firestore データベースへのインポートでは、デフォルト以外の名前空間（Datastore API）からデータをインポートできません。

  デフォルト以外の名前空間を含むデータファイルから MongoDB 互換の Firestore データベースへのインポートは、エクスポート オペレーションにデフォルトの名前空間を含む --namespace-ids フィルタが含まれている場合にのみ許可されます。デフォルトの名前空間のデータのみがインポートされます。

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

Google Cloud Console

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

   [データベース] に移動

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: データベースの名前。

次に例を示します。

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

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

Cloud Storage ブラウザを開く

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

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

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

Google Cloud Console

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

gcloud

エクスポート ファイルのセットから特定のコレクションをインポートするには、--collection-ids フラグを使用します。このオペレーションでインポートされるのは、指定したコレクション ID を持つコレクションのみです。--database フラグを使用してデータベース名を指定します。

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

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

PITR データを含むエクスポートからインポートする

すべてのドキュメントをインポートするまたは特定のコレクションをインポートすると同じ手順で、PITR データをインポートします。データベースにすでにドキュメントが存在する場合は上書きされます。

データのエクスポート

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

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

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

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

Google Cloud Console

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

   [データベース] に移動

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

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

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

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

6. [データベースの現在の状態をエクスポートする] を選択して、現在のデータをエクスポートします。

7. [エクスポート先] セクションで、Cloud Storage バケットの名前を入力するか、[参照] ボタンを使用してバケットを選択します。

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

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

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: ドキュメントのエクスポート元のデータベースの名前。

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

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

Google Cloud Console

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

   [データベース] に移動

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

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

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

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

6. [データベースの現在の状態をエクスポートする] を選択して、現在のデータをエクスポートします。

7. [エクスポート先] セクションで、Cloud Storage バケットの名前を入力するか、[参照] ボタンを使用してバケットを選択します。

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

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

gcloud

特定のコレクションをエクスポートするには、--collection-ids フラグを使用します。このオペレーションでエクスポートされるのは、指定したコレクション ID を持つコレクションのみです。

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

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

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

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

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

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

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

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

コンソール

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

   [データベース] に移動
2. データベースのリストからデータベースを選択します。
3. ナビゲーション メニューで [インポート / エクスポート] をクリックします。
4. [エクスポート] をクリックします。
5. データベース全体または特定のコレクションのみをエクスポートするようにエクスポート ソースを構成します。

6. [エクスポートするデータベースの状態を選択] セクションで、[過去のある時点からエクスポートする] を選択します。

   エクスポートに使用するスナップショット時間を選択する

7. [エクスポート先] セクションで、Cloud Storage バケットの名前を入力するか、[参照] ボタンを使用してバケットを選択します。

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

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

gcloud

gcloud firestore export コマンドを使用すると、PITR データから Cloud Storage にデータベースをエクスポートできます。

snapshot-time パラメータをリカバリ タイムスタンプに指定して、データベースをエクスポートします。次のコマンドを実行して、データベースをバケットにエクスポートします。

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

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

特定のコレクションをエクスポートするには、--collection-ids フラグを追加します。

エクスポートとインポートのオペレーションを管理する

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

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

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

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

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

Google Cloud Console

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

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

   [データベース] に移動

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

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

gcloud

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

gcloud firestore operations list

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

Google Cloud Console

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

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

   [データベース] に移動

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

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

gcloud

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

gcloud firestore operations describe [OPERATION_NAME]

完了時間を予測する

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

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

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

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

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

Google Cloud Console

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

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

   [データベース] に移動

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 プロジェクトに対する課金を有効にする必要があります。

エクスポート オペレーションとインポート オペレーションでは、読み取りユニットと書き込みユニットに対して MongoDB 互換の Firestore の料金に記載されている料金が課金されます。

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

オペレーションが完了するまで、エクスポート / インポート オペレーションで Google Cloud の予算アラートはトリガーされません。エクスポートとインポートのオペレーションは、コンソールの使用状況セクションに表示される使用量には反映されません。

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

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

注: 2020 年 9 月 8 日より前に実行されたエクスポートとインポートのオペレーションでは、goog-firestoremanaged ラベルは適用されていません。

BigQuery にエクスポートする

MongoDB 互換性のある Firestore のエクスポートから BigQuery にデータを読み込むことができますが、collection-ids フィルタを指定した場合に限られます。MongoDB 互換の Firestore エクスポートからのデータの読み込みをご覧ください。

MongoDB 互換性のあるデータを Firestore から BigQuery に読み込む場合、BSON データ型は STRING データ型で表されます。

BigQuery の列の上限

BigQuery では、テーブルあたりの列の数が 10,000 に制限されています。MongoDB 互換の Firestore のエクスポート オペレーションでは、コレクションごとに BigQuery テーブル スキーマが生成されます。このスキーマでは、コレクション グループに含まれる一意のフィールド名のそれぞれがスキーマの列になります。

コレクションの BigQuery スキーマの列数が 10,000 列を超える場合、MongoDB 互換の Firestore のエクスポート オペレーションでは列数の上限内に収まるように、マップ フィールドをバイトとして扱います。この変換によって列数が 10,000 を下回れば、データを BigQuery に読み込むことができますが、マップ フィールド内のサブフィールドのクエリは行えません。列数がそれでも 10,000 を下回らない場合は、エクスポート オペレーションによってコレクションの BigQuery スキーマは生成されず、BigQuery にデータを読み込めません。

エクスポート形式とメタデータ ファイル

マネージド エクスポートの出力では、LevelDB ログ形式が使用されます。

メタデータ ファイル

エクスポート オペレーションでは、指定したコレクション グループごとにメタデータ ファイルが作成されます。通常、メタデータ ファイルの名前は ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata です。

メタデータ ファイルはプロトコル バッファであり、protoc プロトコル コンパイラでデコードできます。たとえば、メタデータ ファイルをデコードして、エクスポート ファイルに含まれるコレクションを判別できます。

protoc --decode_raw < export0.export_metadata