このページでは、マネージド エクスポートとインポート サービスを使用して 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ファイルの名前を同じにしてください。
準備
マネージド エクスポートおよびインポート サービスを使用するには、その前に、次のタスクを完了する必要があります。
Google Cloud プロジェクトに対する課金を有効にします。エクスポート機能とインポート機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。
Cloud Storage バケットは、Datastore モードのデータベースの Firestore と同じ場所に作成する必要があります。エクスポート / インポート オペレーションには、リクエスト元による支払いバケットは使用できません。
ユーザー アカウントに、
datastore.databases.export権限（データをエクスポートする場合）またはdatastore.databases.import権限（データをインポートする場合）を付与する IAM ロールを割り当てます。たとえば、Datastore Import Export Adminロールは、この両方の権限を付与します。Cloud Storage バケットが別のプロジェクトにある場合は、Firestore サービス エージェントにバケットへのアクセス権を付与します。
プロジェクトの gcloud を設定する
gcloud を使用してインポート オペレーションとエクスポート オペレーションを開始する場合は、次のいずれかの方法で gcloud を設定し、プロジェクトに接続します。
Cloud Shell を使用して、Google Cloud Console から
gcloudにアクセスします。現在のプロジェクトを使用するように gcloud CLI を構成します。
gcloud config set project project-id
権限
エクスポートおよびインポートのオペレーションを実行するには、ユーザー アカウントとプロジェクトの 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 サービス アカウントを使用しているかを確認することもできます。
-
Google Cloud コンソールで [データベース] ページに移動します。
-
データベースのリストから、必要なデータベースを選択します。
-
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
- [インポート / エクスポート ジョブの実行方法] ラベルの横にある承認アカウントを表示します。
オペレーションをエクスポートする
別のプロジェクトのバケットが関連するエクスポート オペレーションの場合、バケットの権限を変更して、Datastore モードのデータベースを含むプロジェクトの Datastore モード サービス エージェントに次のいずれかの Identity and Access Management のロールを割り当てます。
- ストレージ管理者
- オーナー（基本ロール）
上記のロールに含まれる権限とは少し異なる権限を持たせたIAM カスタムロールも作成できます。
storage.buckets.getstorage.objects.createstorage.objects.deletestorage.objects.list
オペレーションをインポートする
別のプロジェクトの Cloud Storage バケットが関連するインポート オペレーションの場合、バケットの権限を変更して、Datastore モードのデータベースを含むプロジェクトの Datastore モード サービス エージェントに次のいずれかの Cloud Storage のロールを割り当てます。
- ストレージ管理者
- ストレージ オブジェクト閲覧者とストレージのレガシー バケット読み取りの両方
次の権限を持つ IAM カスタムロールを作成することもできます。
storage.buckets.getstorage.objects.get
マネージド エクスポートおよびインポート オペレーションの開始
このセクションでは、マネージド エクスポートまたはインポート オペレーションを開始する方法について説明します。
すべてのエンティティのエクスポート
Console
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
- ナビゲーション メニューで [インポート / エクスポート] をクリックします。
- [エクスポート] をクリックします。
- [名前空間] を
All Namespacesに設定し、[種類] をAll Kindsに設定します。 - [移行先] に Cloud Storage バケットの名前を入力します。
- [エクスポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。アラートによって、マネージド エクスポート リクエストの成功または失敗が報告されます。
gcloud
gcloud firestore export コマンドを使用して、データベース内のすべてのエンティティをエクスポートします。
gcloud firestore export gs://bucket-name --async --database=DATABASE
ここで、bucket-nameは Cloud Storage バケットの名前とオプションの接頭辞です（例: bucket-name/datastore-exports/export-name）。別のエクスポート オペレーションで同じ接頭辞を再利用することはできません。ファイル接頭辞を指定しない場合、マネージド エクスポート サービスは現在の時刻に基づいてエクスポートを作成します。
オペレーションが完了するまで gcloud を待機させないようにするには、[--async][async-flag] フラグを使用します。--async フラグを省略した場合、Ctrl+c を入力するとオペレーションが完了するまで待機することは止めますが、これによってオペレーションがキャンセルされることはありません。
--database フラグを、エンティティをエクスポートする元のデータベースの名前に設定します。デフォルト データベースの場合は、--database='(default)' を使用します。
rest
リクエストのデータを使用する前に、次のように置き換えます。
- project-id: プロジェクト ID
- bucket-name: Cloud Storage バケット名
HTTP メソッドと URL:
POST https://datastore.googleapis.com/v1/projects/project-id:export
JSON 本文のリクエスト:
{
"outputUrlPrefix": "gs://bucket-name",
}
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"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 個までに制限されています。フィルタリング対象の種類と名前空間の各組み合わせが、別々のフィルタとしてこの上限に対しカウントされます。
Console
Console では、すべての種類または特定の 1 種類のいずれかを選択できます。名前空間も同様に、すべてまたは特定の 1 つを選択できます。
エクスポートする名前空間と種類のリストを指定するには、代わりに gcloud を使用します。
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
[エクスポート] をクリックします。
[名前空間] を
All Namespaces（すべての名前空間）またはいずれかの名前空間の名前に設定します。[種類] を
All Kinds（すべての種類）または種類の名前に設定します。[移行先] に Cloud Storage バケットの名前を入力します。
[エクスポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。アラートによって、マネージド エクスポート リクエストの成功または失敗が報告されます。
gcloud
gcloud firestore export --collection-ids="KIND1,KIND2" \ --namespaces="(default),NAMESPACE2" \ gs://bucket-name \ --async \ --database=DATABASE
ここで、bucket-nameは Cloud Storage バケットの名前とオプションの接頭辞です（例: bucket-name/datastore-exports/export-name）。別のエクスポート オペレーションで同じ接頭辞を再利用することはできません。ファイル接頭辞を指定しない場合、マネージド エクスポート サービスは現在の時刻に基づいてエクスポートを作成します。
オペレーションが完了するまで gcloud を待機させないようにするには、[--async][async-flag] フラグを使用します。--async フラグを省略した場合、Ctrl+c を入力するとオペレーションが完了するまで待機することは止めますが、これによってオペレーションがキャンセルされることはありません。
--database フラグを、特定の種類または名前空間をエクスポートする元のデータベースの名前に設定します。デフォルト データベースの場合は、--database='(default)' を使用します。
rest
リクエストのデータを使用する前に、次のように置き換えます。
- project-id: プロジェクト ID
- bucket-name: Cloud Storage バケット名
- kind: エンティティの種類
- namespace: 名前空間 ID（デフォルトの名前空間 ID には「""」を使用します）
HTTP メソッドと URL:
POST https://datastore.googleapis.com/v1/projects/project-id:export
JSON 本文のリクエスト:
{
"outputUrlPrefix": "gs://bucket-name",
"entityFilter": {
"kinds": ["kind"],
"namespaceIds": ["namespace"],
},
}
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"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
すべてのエンティティのインポート
Console
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
[インポート] をクリックします。
Fileで [参照] をクリックし、.overall_export_metadataファイルを選択します。.overall_export_metadataファイルがデフォルトの場所から移動されていないことを確認してください。[名前空間] を
All Namespacesに設定し、[種類] をAll Kindsに設定します。[インポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。アラートによって、マネージド エクスポート リクエストの成功または失敗が報告されます。
gcloud
マネージド エクスポート サービスで以前にエクスポートされたすべてのエンティティをインポートするには、gcloud firestore import コマンドを使用します。
gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \ --async \ --database=DATABASE
ここで、bucket-name/file-path/file-name は Cloud Storage バケット内の overall_export_metadata ファイルへのパスです。
オペレーションが完了するまで gcloud を待機させないようにするには、[--async][async-flag] フラグを使用します。--async フラグを省略した場合、Ctrl+c を入力するとオペレーションが完了するまで待機することは止めますが、これによってオペレーションがキャンセルされることはありません。
--database フラグを、すべてのエンティティをインポートするデータベースの名前に設定します。デフォルト データベースの場合は、--database='(default)' を使用します。
rest
リクエストのデータを使用する前に、次のように置き換えます。
- project-id: プロジェクト ID
- bucket-name: Cloud Storage バケット名
- object-name: Cloud Storage オブジェクト名（例:
2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata
HTTP メソッドと URL:
POST https://datastore.googleapis.com/v1/projects/project-id:import
JSON 本文のリクエスト:
{
"inputUrl": "gs://bucket-name/object-name",
}
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"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 Console の 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 の値を指定します。
エクスポート ファイルがエンティティ フィルタで作成された場合にのみ、種類と名前空間を指定できます。すべてのエンティティのエクスポートから、種類と名前空間のサブセットをインポートすることはできません。
Console
Console では、すべての種類または特定の 1 種類のいずれかを選択できます。名前空間も同様に、すべてまたは特定の 1 つを選択できます。
インポートする名前空間と種類のリストを指定するには、代わりに gcloud を使用します。
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
[インポート] をクリックします。
Fileで [参照] をクリックし、.overall_export_metadataファイルを選択します。.export_metadataファイルではなく.overall_export_metadataファイルをインポートしてください。[名前空間] を
All Namespacesまたは特定の名前空間に設定します。[種類] を
All Kindsまたは特定の種類に設定します。[インポート] をクリックします。
コンソールが [インポート / エクスポート] ページに戻ります。アラートによって、マネージド エクスポート リクエストの成功または失敗が報告されます。
gcloud
gcloud firestore import --collection-ids="KIND1,KIND2" \ --namespaces="(default),NAMESPACE2" \ gs://bucket-name/file-path/file-nameoverall_export_metadata \ --async \ --database=DATABASE
ここで、bucket-name/file-path/file-name は Cloud Storage バケット内の overall_export_metadata ファイルへのパスです。
オペレーションが完了するまで gcloud を待機させないようにするには、[--async][async-flag] フラグを使用します。--async フラグを省略した場合、Ctrl+c を入力するとオペレーションが完了するまで待機することは止めますが、これによってオペレーションがキャンセルされることはありません。
--database フラグを、特定の種類または名前空間をインポートするデータベースの名前に設定します。デフォルト データベースの場合は、--database='(default)' を使用します。
rest
リクエストのデータを使用する前に、次のように置き換えます。
- project-id: プロジェクト ID
- bucket-name: Cloud Storage バケット名
- object-name: Cloud Storage オブジェクト名（例:
2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata - kind: エンティティの種類
- namespace: 名前空間 ID（デフォルトの名前空間 ID には「""」を使用します）
HTTP メソッドと URL:
POST https://datastore.googleapis.com/v1/projects/project-id:import
JSON 本文のリクエスト:
{
"inputUrl": "gs://bucket-name/object-name",
"entityFilter": {
"kinds": ["kind"],
"namespaceIds": ["namespace"],
},
}
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"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 データからエクスポートおよびインポートする
gcloud firestore export コマンドを使用すると、PITR データから Cloud Storage にデータベースをエクスポートできます。タイムスタンプが過去 7 日以内（ただし earliestVersionTime 以降）の 1 分単位の場合は、PITR データをエクスポートできます。指定したタイムスタンプにデータがもう存在しない場合、エクスポート オペレーションは失敗します。
PITR エクスポート オペレーションでは、すべてのエンティティのエクスポート、特定の種類または名前空間のエクスポートなど、すべてのフィルタがサポートされます。
snapshot-timeパラメータを必要なリカバリ タイムスタンプに指定して、データベースをエクスポートします。gcloud
次のコマンドを実行して、データベースをバケットにエクスポートします。
gcloud firestore export gs://[BUCKET_NAME_PATH] \ --snapshot-time=[PITR_TIMESTAMP] \ --collection-ids=[COLLECTION_IDS] \ --namespace-ids=[NAMESPACE_IDS]ここで
PITR_TIMESTAMP- 分単位の PITR タイムスタンプ（例:2023-05-26T10:20:00.00Z）。
[エンティティ フィルタを使用して種類や名前空間の特定のサブセットをエクスポートする][export-kind] こともできます。
PITR データをエクスポートする前に、次の点に注意してください。
- RFC 3339 形式でタイムスタンプを指定します例:
2020-09-01T23:59:30.234233Z - タイムスタンプは、過去 1 時間以内（ただし
earliestVersionTime以降）の 1 分単位のタイムスタンプを指定する必要があります。指定したタイムスタンプにデータが存在しない場合は、エラーが発生します。 - 失敗した PITR エクスポートについては課金されません。
データベースにインポートします。
すべてのエンティティのインポートの手順に沿って、エクスポートしたデータベースをインポートします。データベースにすでにエンティティが存在する場合は上書きされます。[エンティティ フィルタを使用して種類や名前空間の特定のサブセットをインポートする][import-kind] こともできます。
変換をインポートする
別のプロジェクトからエンティティをインポートするときは、エンティティ キーにプロジェクト ID が含まれていることに注意してください。インポート オペレーションでは、インポート データのエンティティ キーとキー参照プロパティを宛先プロジェクトのプロジェクト ID で更新します。この更新によりエンティティ サイズが大きくなる場合、インポート オペレーションで「エンティティが大きすぎる」または「インデックス エントリが大きすぎる」というエラーが発生する可能性があります。
これらのエラーを回避するには、短いプロジェクト ID で宛先プロジェクトにインポートします。同じプロジェクトのデータが含まれるインポート オペレーションには影響しません。
長時間実行オペレーションの管理
マネージド インポートおよびエクスポート オペレーションは、長時間実行オペレーションです。これらのメソッド呼び出しには、かなりの時間がかかることがあります。
エクスポートまたはインポート オペレーションの開始後は、Datastore モードによって、オペレーションに一意の名前が割り当てられます。このオペレーション名を使用して、オペレーションの削除、取り消し、状況確認を行うことができます。
次のように、オペレーション名の先頭には projects/[PROJECT_ID]/databases/(default)/operations/ という文字列が付きます。
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
gcloud コマンド用のオペレーション名を指定するときは、接頭辞を省略できます。
すべての長時間実行オペレーションの一覧表示
進行中のオペレーションと最近完了したオペレーションは、次の方法で表示できます。オペレーションは、完了後数日間一覧表示されます。
Console
長時間実行オペレーションの一覧は、Google Cloud コンソールの [インポート / エクスポート] ページで確認できます。
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
gcloud
長時間実行オペレーションを一覧表示するには、gcloud datastore operations list コマンドを使用します。
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"
}
}
]
}
rest
リクエストのデータを使用する前に、次のように置き換えます。
- project-id: プロジェクト ID
HTTP メソッドと URL:
GET https://datastore.googleapis.com/v1/projects/project-id/operations
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスの詳細については、下記をご覧ください。
たとえば、最近完了したエクスポート オペレーションには、次の情報が表示されます。
{
"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"
}
}
]
}
動作状態を確認する
長時間実行オペレーションのステータスを表示するには:
Console
Google Cloud コンソールの [インポート / エクスポート] ページで、最新のエクスポートとインポートのオペレーションを一覧表示できます。
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
gcloud
operations describe コマンドを使用して、長時間実行オペレーションのステータスを表示します。
gcloud datastore operations describe operation-name
rest
リクエストのデータを使用する前に、次のように置き換えます。
- project-id: プロジェクト ID
- operation-name: オペレーション名
HTTP メソッドと URL:
GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
"common": {
"startTime": "2019-10-08T20:07:28.105236Z",
"endTime": "2019-10-08T20:07:36.310653Z",
"operationType": "EXPORT_ENTITIES",
"state": "SUCCESSFUL"
},
"progressEntities": {
"workCompleted": "21",
"workEstimated": "21"
},
"progressBytes": {
"workCompleted": "2272",
"workEstimated": "2065"
},
"entityFilter": {},
"outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
"outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
}
}
完了時間の見積もり
オペレーションを実行すると、state フィールドの値で、オペレーション全体のステータスが確認できます。
長時間実行オペレーションのステータスをリクエストすると、workEstimated 指標と workCompleted 指標が返されます。これらの指標はバイト数とエンティティ数の両方で返されます。
workEstimatedには、オペレーションで処理される推定の合計バイト数とドキュメント数が表示されます。Datastore モードでは、推定できない場合、この指標を省略することがあります。workCompletedには、これまでに処理されたバイト数とドキュメント数が表示されます。オペレーションが完了すると、実際に処理された合計バイト数とドキュメント数が表示されます。workEstimatedの値よりも大きくなる可能性があります。
進行した割合を大まかに得るには、workCompleted を workEstimated で割ります。最新の統計情報コレクションとの間に遅延があるため、この割合は正確ではない可能性があります。
例として、エクスポート オペレーションの進行状況を次に示します。
{
"operations": [
{
"name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
...
"progressEntities": {
"workCompleted": "1",
"workEstimated": "3"
},
"progressBytes": {
"workCompleted": "85",
"workEstimated": "257"
},
...
オペレーションが完了すると、オペレーションの説明に、"done":
true が含まれます。オペレーションの結果をみるには、state フィールドの値を確認します。done フィールドがレスポンスに設定されていない場合、値は false になります。進行中のオペレーションに関しては、done の値の有無は参考になりません。
オペレーションのキャンセル
Console
実行中のエクスポートまたはインポート オペレーションは、Google Cloud コンソールの [インポート / エクスポート] ページでキャンセルできます。
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
[最近のインポートとエクスポート] の表で、現在実行中のオペレーションの [完了] の列に [キャンセル] ボタンが表示されます。[キャンセル] ボタンをクリックして、オペレーションを停止します。ボタンが [キャンセル中] に変わり、オペレーションが完全に停止すると [キャンセル済み] に変わります。
gcloud
進行中のオペレーションを停止するには、operations cancel コマンドを使用します。
gcloud datastore operations cancel operation-name
実行中のオペレーションを取り消しても、オペレーション前の状態には戻りません。エクスポート オペレーションをキャンセルした場合、エクスポート済みのドキュメントは Cloud Storage に残ります。また、インポート オペレーションをキャンセルした場合はデータベースに行われた更新がそのまま残ります。部分的に完了したエクスポートはインポートできません。
オペレーションを削除する
gcloud
最近のオペレーションのリストからオペレーションを削除するには、operations delete コマンドを使用します。このコマンドは、Cloud Storage からエクスポート ファイルを削除しません。
gcloud datastore operations delete operation-name
マネージド エクスポートおよびインポートの課金と料金
マネージド エクスポートおよびインポート サービスを使用する前に、Google Cloud プロジェクトに対する課金を有効にする必要があります。エクスポートとインポートのオペレーションは、次のような形で Google Cloud のコストに反映されます。
- エクスポートとインポートのオペレーションで実行されるエンティティの読み取りと書き込みは、Datastore モードの Firestore のコストにカウントされます。エクスポート オペレーションでは、エクスポートされるエンティティごとに 1 回の読み取りオペレーションが発生します。インポート オペレーションでは、インポートされるエンティティごとに 1 回の書き込みオペレーションが発生します。
- Cloud Storage に保存された出力ファイルは、Cloud Storage のデータ ストレージ コストにカウントされます。
オペレーションが完了するまで、エクスポート / インポート オペレーションで Google Cloud の予算アラートはトリガーされません。同様に、エクスポートまたはインポート オペレーションの実行中に行われる読み取りと書き込みは、オペレーションが完了してから 1 日の割り当てに適用されます。
エクスポートとインポートの料金を確認する
課金対象のオペレーションには、エクスポートとインポートのオペレーションにより goog-firestoremanaged:exportimport ラベルが適用されます。エクスポートとインポートのオペレーションに関連する費用を表示するには、Cloud Billing レポートのページで、このラベルを使用します。
Datastore 管理バックアップとの相違点
以前に Datastore 管理コンソールをバックアップ用に使用していた場合は、次の違いに注意してください。
マネージド エクスポートによって作成されたエクスポートは、Datastore 管理コンソールには表示されません。マネージド エクスポートおよびインポートは新しいサービスであり、Google Cloud コンソールで管理する App Engine のバックアップおよび復元機能とはデータを共有しません。
マネージド エクスポートおよびインポート サービスは、Datastore 管理バックアップと同じメタデータをサポートしているわけではありません。また、データベースに進行状況を保管することはしません。エクスポートおよびインポート オペレーションの進行状況を確認する方法については、長時間実行オペレーションの管理をご覧ください。
マネージド エクスポートおよびインポート オペレーションのサービスログを表示することはできません。
マネージド インポート サービスには、Datastore 管理バックアップ ファイルとの後方互換性があります。マネージド インポート サービスを使用して Datastore 管理バックアップ ファイルをインポートすることはできますが、Datastore 管理コンソールを使用してマネージド エクスポートの出力をインポートすることはできません。
BigQuery へのインポート
マネージド エクスポートから BigQuery にデータをインポートするには、Datastore エクスポート サービスデータの読み込みをご覧ください。
エンティティ フィルタを指定せずにエクスポートされたデータは、BigQuery に読み込むことができません。BigQuery にデータをインポートするには、エクスポート リクエストでエンティティ フィルタに 1 種類以上の名前を含める必要があります。
BigQuery の列の上限
BigQuery では、テーブルあたりの列の数が 10,000 に制限されています。エクスポート オペレーションでは、種類ごとに BigQuery テーブル スキーマが生成されます。このスキーマでは、種類のエンティティに含まれる一意のプロパティのそれぞれがスキーマの列になります。
種類の BigQuery スキーマの列数が 10,000 列を超える場合、エクスポート オペレーションでは列数の上限内に収まるように、埋め込みエンティティを blob として扱います。この変換によってスキーマの列数が 10,000 を下回った場合、BigQuery にデータを読み込むことはできますが、埋め込みエンティティ内のプロパティに対してクエリを実行することはできません。変換しても列数が 10,000 より多い場合は、エクスポート オペレーションによって種類の BigQuery スキーマは生成されず、BigQuery にデータを読み込めません。
サービス エージェントの移行
Firestore は、App Engine サービス アカウントを使用する代わりに、Firestore サービス エージェントを使用してインポートとエクスポートのオペレーションを承認します。サービス エージェントとサービス アカウントは、次の命名規則を使用します。
- Firestore サービス エージェント
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com
Firestore では、以前は Firestore サービス エージェントの代わりに App Engine のデフォルトのサービス アカウントを使用していました。データベースが依然として App Engine サービス アカウントを使用してデータをインポートまたはエクスポートしている場合は、このセクションの手順に沿って Firestore サービス エージェントの使用に移行することをおすすめします。
- App Engine サービス アカウント
PROJECT_ID@appspot.gserviceaccount.com
Firestore サービス エージェントは Firestore に固有であるため、Firestore サービス エージェントをおすすめします。App Engine サービス アカウントは、複数のサービスで共有されます。
承認アカウントを表示する
リクエストを承認するためにインポートとエクスポートのオペレーションで使用するアカウントは、Google Cloud コンソールの [インポート / エクスポート] ページで確認できます。データベースが、すでに Firestore サービス エージェントを使用しているかどうかも確認できます。
-
Google Cloud コンソールで [データベース] ページに移動します。
- データベースのリストから、必要なデータベースを選択します。
-
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
- [インポート / エクスポート ジョブの実行方法] ラベルの横にある承認アカウントを表示します。
プロジェクトで Firestore サービス エージェントを使用していない場合は、次のいずれかの方法で Firestore サービス エージェントに移行できます。
- Cloud Storage バケットの権限を確認して更新することで、プロジェクトを移行する（推奨）。
- 組織内のすべてのプロジェクトに適用される組織全体のポリシー制約を追加します。
1 番目は、単一の Datastore モード プロジェクトに効果の範囲をローカライズするため、望ましい方法です。2 番目の方法は、既存の Cloud Storage バケットの権限を移行しないため、推奨しません。ただし、組織レベルでのセキュリティ コンプライアンスは実現します。
Cloud Storage バケットの権限を確認および更新して移行する
移行プロセスには次の 2 つの手順があります。
- Cloud Storage バケットの権限を更新します。詳細は以下で説明します。
- Firestore サービス エージェントへの移行を確認します。
サービス エージェント バケットの権限
別のプロジェクトの Cloud Storage バケットを使用するエクスポートまたはインポート オペレーションの場合は、そのバケットに対する Firestore サービス エージェント権限を付与する必要があります。たとえば、データを別のプロジェクトに移動するオペレーションは、その別のプロジェクト内のバケットにアクセスする必要があります。そうでないと、これらのオペレーションは Firestore サービス エージェントへの移行後に失敗します。
同じプロジェクト内にあるインポートとエクスポートのワークフローでは、権限の変更は必要ありません。デフォルトでは、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 サービス アカウントから Firestore サービス エージェントに移行するには、次の手順を行います。完了すると、移行は元に戻せません。
-
Google Cloud コンソールで [データベース] ページに移動します。
- データベースのリストから、必要なデータベースを選択します。
-
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
-
プロジェクトがまだ Firestore サービス エージェントに移行していない場合は、移行を説明するバナーと [バケットのステータスを確認] ボタンが表示されます。次の手順では、潜在的な権限エラーを特定して修正します。
[バケットのステータスを確認] をクリックします。
移行を完了するためのオプションと Cloud Storage バケットのリストが記載されたメニューが表示されます。リストの読み込みが完了するまで数分かかることがあります。
このリストには、インポートとエクスポートのオペレーションで最近使用されたバケットが含まれていますが、Datastore モード サービス エージェントへの読み取りと書き込みの権限は現在は付与されていません。
- プロジェクトの Datastore モード サービス エージェントのプリンシパル名をメモします。サービス エージェント名は、[アクセス権を付与するサービス エージェント] ラベルの下に表示されます。
-
リスト内のバケットのうち、今後のインポートまたはエクスポート オペレーションに使用する場合は、次の手順を行います。
-
このバケットの表の行で [修正] をクリックします。そのバケットの権限ページが新しいタブで開きます。
- [追加] をクリックします。
- [新しいプリンシパル] フィールドに、Firestore サービス エージェントの名前を入力します。
- [ロールを選択] フィールドで、[サービス エージェント] > [Firestore サービス エージェント] の順に選択します。
- [保存] をクリックします。
- Datastore モードのインポート / エクスポート ページがあるタブに戻ります。
- リスト内の他のバケットについて、上記の手順を繰り返します。リストのすべてのページを表示してください。
-
-
[Firestore サービス エージェントに移行] をクリックします。権限チェックに失敗したバケットがまだある場合は、[Migrate] をクリックして移行を確認する必要があります。
移行が完了するとアラートが表示されます。移行は元に戻せません。
移行ステータスを表示する
プロジェクトの移行ステータスを確認するには:
-
Google Cloud コンソールで [データベース] ページに移動します。
- データベースのリストから、必要なデータベースを選択します。
-
ナビゲーション メニューで [インポート / エクスポート] をクリックします。
-
[インポート / エクスポート ジョブの実行方法] ラベルの横にあるプリンシパルを探します。
プリンシパルが
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.comの場合、プロジェクトはすでに Firestore サービス エージェントに移行されています。移行は元に戻せません。プロジェクトが移行されていない場合は、[バケットのステータスを確認] ボタンでページ上部にバナーが表示されます。移行を完了するには、Firestore サービス エージェントに移行するをご覧ください。
組織全体のポリシーの制約を追加する
-
組織のポリシーに次の制約を設定します。
インポート / エクスポート用に必要な Firestore サービス エージェント（
firestore.requireP4SAforImportExport）この制約により、インポートおよびエクスポート操作では、Firestore サービス エージェントを使用してリクエストを承認する必要があります。 この制約を設定するには、組織のポリシーの作成と管理をご覧ください。
この組織のポリシー制約を適用しても、Firestore サービス エージェントに適切な Cloud Storage バケット権限が自動的に付与されることはありません。
制約によってインポートまたはエクスポートのワークフローの権限エラーが発生した場合は、デフォルトのサービス アカウントを使用して制約を無効にし、元に戻すことができます。Cloud Storage バケットの権限を確認および更新した後、制約を再び有効にできます。