エンティティのエクスポートとインポート

このページでは、マネージド エクスポートとインポート サービスを使用して Datastore モードの Firestore エンティティをエクスポート、インポートする方法について説明します。マネージド エクスポートおよびインポート サービスは、 Google Cloud コンソール、Google Cloud CLI、Datastore Admin API（REST、RPC）で利用できます。

マネージド エクスポートおよびインポート サービスを利用すると、誤って削除したデータを復元したり、オフライン処理のためにデータをエクスポートしたりできます。すべてのエンティティをエクスポートすることも、特定の種類のエンティティだけをエクスポートすることもできます。同様に、エクスポートされたすべてのデータをインポートすることも、特定の種類のみをインポートすることもできます。マネージド エクスポートおよびインポート サービスを利用する際は、次の点を考慮してください。

• エクスポート サービスでは、結果整合性読み取りが使用されます。エクスポートが単一の時点で発生すると想定することはできません。エクスポートの開始後に書き込まれたエンティティがエクスポートに含まれる場合も、エクスポートの開始前に書き込まれたエンティティがエクスポートから除外される場合もあります。

• インデックスはエクスポートに含まれません。データをインポートすると、データベースの現在のインデックス定義を使用して、必要なインデックスが自動的に再構築されます。エンティティごとのプロパティ値のインデックス設定はエクスポートされ、インポート時に適用されます。

• インポートでは、エンティティに新しい ID は割り当てられません。インポートでは、エクスポート時の ID が使用され、同じ ID のエンティティはすべて上書きされます。これらの ID は、エンティティのインポート中は予約された状態になります。これにより、インポートの実行中に書き込みが有効になっても、新しいエンティティと ID が競合することはありません。

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

• ある Datastore モードのデータベースからエクスポートされたデータを、別の Datastore モードのデータベース（別のプロジェクト内のものでも可）にインポートできます。

• マネージド エクスポートおよびインポート サービスでは、同時に実行できるエクスポートとインポートの数が 50 に制限されています。プロジェクトで 1 分間に送信できるエクスポート / インポート リクエストは最大 20 個までです。リクエストごとに、サービスではエンティティ フィルタの組み合わせの数が 100 個に制限されます。

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

• エンティティのサブセットのみインポートする場合、もしくは BigQuery にデータをインポートする場合は、エクスポートでエンティティ フィルタを指定する必要があります。

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

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

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

準備

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

1. Google Cloud プロジェクトに対する課金を有効にします。エクスポート機能とインポート機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。

2. Cloud Storage バケットは、Datastore モードのデータベースの Firestore と同じ場所に作成する必要があります。エクスポート / インポート オペレーションには、リクエスト元による支払いバケットまたはRapid Bucketは使用できません。

3. ユーザー アカウントに、datastore.databases.export 権限（データをエクスポートする場合）または datastore.databases.import 権限（データをインポートする場合）を付与する IAM ロールを割り当てます。たとえば、Datastore Import Export Admin ロールは、この両方の権限を付与します。

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

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

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

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

  Cloud Shell の起動

  現在のプロジェクトを使用するように gcloud CLI を構成します。

  gcloud config set project project-id
  

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

権限

エクスポートおよびインポートのオペレーションを実行するには、ユーザー アカウントとプロジェクトの Datastore モード サービス エージェントに Identity and Access Management の次の権限が必要です。

ユーザー アカウント権限

オペレーションを開始するユーザー アカウントまたはサービス アカウントには、datastore.databases.export と datastore.databases.import の IAM 権限が必要です。プロジェクト オーナーであれば、アカウントに必要な権限が付与されています。そうでない場合は、次の IAM ロールにより、必要な権限を付与します。

• データストア オーナー
• Datastore インポート / エクスポート管理者

これらの権限をカスタムロールに割り当てることもできます。

プロジェクト オーナーがアクセスの許可の手順に従ってこれらのロールのいずれかを付与します。

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

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

Firestore サービス エージェント

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

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

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

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

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

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

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

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

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

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

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

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

   [データベース] に移動

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

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

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

オペレーションをエクスポートする

別のプロジェクトのバケットが関連するエクスポート オペレーションの場合、バケットの権限を変更して、Datastore モードのデータベースを含むプロジェクトの Datastore モード サービス エージェントに次のいずれかの Identity and Access Management のロールを割り当てます。

• ストレージ管理者
• オーナー（基本ロール）

上記のロールに含まれる権限とは少し異なる権限を持たせたIAM カスタムロールも作成できます。

• storage.buckets.get
• storage.objects.create
• storage.objects.delete
• storage.objects.list

オペレーションをインポートする

別のプロジェクトの Cloud Storage バケットが関連するインポート オペレーションの場合、バケットの権限を変更して、Datastore モードのデータベースを含むプロジェクトの Datastore モード サービス エージェントに次のいずれかの Cloud Storage のロールを割り当てます。

• ストレージ管理者
• ストレージ オブジェクト閲覧者とストレージのレガシー バケット読み取りの両方

次の権限を持つ IAM カスタムロールを作成することもできます。

• storage.buckets.get
• storage.objects.get

マネージド エクスポートおよびインポート オペレーションの開始

このセクションでは、マネージド エクスポートまたはインポート オペレーションを開始する方法について説明します。

すべてのエンティティのエクスポート

 gcloud firestore export gs://bucket-name --async --database=DATABASE

POST https://datastore.googleapis.com/v1/projects/project-id:export

{
  "outputUrlPrefix": "gs://bucket-name",
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}

特定の種類または名前空間のエクスポート

種類や名前空間の特定のサブセットをエクスポートするには、エンティティ フィルタに種類と名前空間 ID の値を指定します。リクエストごとに、エンティティ フィルタの組み合わせは 100 個までに制限されています。フィルタリング対象の種類と名前空間の各組み合わせが、別々のフィルタとしてこの上限に対しカウントされます。

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

POST https://datastore.googleapis.com/v1/projects/project-id:export

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}

メタデータ ファイル

エクスポート オペレーションでは、指定された名前空間と種類のペアごとにメタデータ ファイルが作成されます。通常、メタデータ ファイルの名前は NAMESPACE_NAME_KIND_NAME.export_metadata です。ただし、名前空間または種類で無効な Cloud Storage オブジェクト名が作成された場合には、ファイル名が export[NUM].export_metadata になります。

メタデータ ファイルはプロトコル バッファであり、protocプロトコル コンパイラでデコードできます。たとえば、メタデータ ファイルをデコードすると、エクスポート ファイルに含まれる名前空間と種類を判別することができます。

protoc --decode_raw < export0.export_metadata

すべてのエンティティのインポート

gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \
--async \
--database=DATABASE

POST https://datastore.googleapis.com/v1/projects/project-id:import

{
  "inputUrl": "gs://bucket-name/object-name",
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:import"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:import" | Select-Object -Expand Content

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}

overall_export_metadata ファイルの検索

インポートの場所に使用する値は、 Google Cloud コンソールの Cloud Storage ブラウザで次のように指定できます。

Cloud Storage ブラウザを開く

完了したオペレーションをリストして説明することもできます。outputURL には、overall_export_metadata ファイルの名前が表示されます。

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

特定の種類または名前空間のインポート

種類や名前空間の特定のサブセットをインポートするには、エンティティ フィルタに種類と名前空間 ID の値を指定します。

エクスポート ファイルがエンティティ フィルタで作成された場合にのみ、種類と名前空間を指定できます。すべてのエンティティのエクスポートから、種類と名前空間のサブセットをインポートすることはできません。

  gcloud firestore import --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name/file-path/file-nameoverall_export_metadata \
  --async \
  --database=DATABASE

POST https://datastore.googleapis.com/v1/projects/project-id:import

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:import"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:import" | Select-Object -Expand Content

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}

PITR データからエクスポートおよびインポートする

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

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

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

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

gcloud firestore export gs://[BUCKET_NAME_PATH] \
          --snapshot-time=[PITR_TIMESTAMP] \
          --collection-ids=[COLLECTION_IDS] \
          --namespace-ids=[NAMESPACE_IDS]

変換をインポートする

別のプロジェクトからエンティティをインポートするときは、エンティティ キーにプロジェクト ID が含まれていることに注意してください。インポート オペレーションでは、インポート データのエンティティ キーとキー参照プロパティを宛先プロジェクトのプロジェクト ID で更新します。この更新によりエンティティ サイズが大きくなる場合、インポート オペレーションで「エンティティが大きすぎる」または「インデックス エントリが大きすぎる」というエラーが発生する可能性があります。

これらのエラーを回避するには、短いプロジェクト ID で宛先プロジェクトにインポートします。同じプロジェクトのデータが含まれるインポート オペレーションには影響しません。

長時間実行オペレーションの管理

マネージド インポートおよびエクスポート オペレーションは、長時間実行オペレーションです。これらのメソッド呼び出しには、かなりの時間がかかることがあります。

エクスポートまたはインポート オペレーションの開始後は、Datastore モードによって、オペレーションに一意の名前が割り当てられます。このオペレーション名を使用して、オペレーションの削除、取り消し、状況確認を行うことができます。

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

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

gcloud コマンド用のオペレーション名を指定するときは、接頭辞を省略できます。

すべての長時間実行オペレーションの一覧表示

進行中のオペレーションと最近完了したオペレーションは、次の方法で表示できます。オペレーションは、完了後数日間一覧表示されます。

gcloud datastore operations list

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

GET https://datastore.googleapis.com/v1/projects/project-id/operations

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

動作状態を確認する

長時間実行オペレーションのステータスを表示するには:

gcloud datastore operations describe operation-name

GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name