ポイントインタイムリカバリ（PITR）の使用

このページでは、ポイントインタイムリカバリ（PITR）を使用して、Datastore モードの Firestore でデータを保持および復元する方法について説明します。

PITR のコンセプトを理解するには、ポイントインタイムリカバリをご覧ください。

権限

PITR 設定を管理するために必要な権限を取得するには、PITR 設定を有効にするプロジェクトに対する Cloud Datastore オーナー（roles/datastore.owner）の IAM ロール付与を管理者に依頼してください。ロールの付与の詳細については、アクセスの管理をご覧ください。

この事前定義ロールには、PITR 設定を管理するために必要な権限が含まれています。必要な権限を正確に確認するには、[必要な権限] セクションを開いてください。

必要な権限

PITR 設定を管理するには、次の権限が必要です。

データベース作成時の PITR の有効化: datastore.databases.create
既存のデータベースの PITR 設定の更新: datastore.databases.update,datastore.databases.list
PITR データからの読み取りの実行: datastore.databases.get,datastore.entities.get,datastore.entities.list,datastore.namespaces.get,datastore.namespaces.list,datastore.statistics.get,datastore.statistics.list
PITR データのエクスポート: datastore.databases.export
PITR データのインポート: datastore.databases.import

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

準備

PITR の使用を開始する前に、次の点に注意してください。

PITR を有効にした直後は、7 日前からの読み取りを開始できません。
データベース作成時の PITR を有効にする場合は、gcloud firestore databases create コマンドを使用する必要があります。Google Cloud コンソールを使用してデータベースを作成するときに PITR を有効にすることはできません。
Datastore モードでは、PITR を有効にした後、その時点からのバージョンの保持を開始します。
PITR を無効にすると、PITR データの保持期間内であっても PITR データを読み取ることができなくなります。
PITR を無効にした直後に再度有効にした場合、過去の PITR データは使用できなくなります。PITR を無効にする前に作成された PITR データは、PITR の有効期限の後に削除されます。
過去 1 時間以内に誤ってデータを削除し、PITR が無効になっている場合は、削除後 1 時間以内であれば PITR を有効にするとデータを復元できます。
期限切れの PITR データに対する読み取りはすべて失敗します。

PITR を有効にする

PITR を使用する前に、Google Cloud プロジェクトに対する課金を有効にします。PITR 機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。

データベースの PITR を有効にするには:

コンソール

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

[データベース] に移動
データベースのリストから、必要なデータベースを選択します。
ナビゲーションメニューで、[障害復旧] をクリックします。
[編集] をクリックして設定を編集します。
[ポイントインタイムリカバリを有効にする] チェックボックスをオンにして、[保存] をクリックします。

PITR を有効にすると、ストレージの費用が発生します。詳細は料金をご覧ください。

PITR を無効にするには、Google Cloud コンソールの [障害復旧] ページで [ポイントインタイムリカバリを有効にする] チェックボックスをオフにします。

gcloud

次のように gcloud firestore databases create コマンドを使用して、データベース作成時の PITR を有効にします。

gcloud firestore databases create\
  --location=LOCATION\
  [--database=DATABASE_ID; default="(default)"]\
  [--type=TYPE; default="firestore-native"]\
  --enable-pitr

次のように置き換えます。

LOCATION - データベースを作成するロケーション。
DATABASE_ID - データベース ID または（default）に設定します。
TYPE - Datastore モードに設定します。

PITR を無効にするには、次のように gcloud firestore databases update コマンドを使用します。

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --no-enable-pitr

次のように置き換えます。

DATABASE_ID - データベース ID または（default）に設定します。

保持期間と最短版の時間を取得する

コンソール

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

[データベース] に移動
データベースのリストから、必要なデータベースを選択します。
ナビゲーションメニューで、[障害復旧] をクリックします。
[設定] セクションの [保持期間] と [最も古いバージョンの時刻] をメモします。
- 保持期間: Datastore モードで、データベースのすべてのバージョンのデータを保持する期間。この値は、PITR が無効になっている場合は 1 時間、PITR が有効になっている場合は 7 日間です。
- 最も古いバージョンの時刻: PITR 期間で古いバージョンのデータを読み取ることができる最も古いタイムスタンプ。この値は Datastore モードによって継続的に更新され、クエリが行われる時点で最新ではなくなっています。この値を使用してデータを復元する場合、値がクエリされてから復元を行うまでの間に経過した時間を考慮する必要があります。
- ポイントインタイムリカバリ: PITR が有効になっている場合は、Enabled が表示されます。PITR が無効になっていると、Disabled が表示されます。

gcloud

gcloud firestore databases describe コマンドを次のように実行します。

gcloud firestore databases describe --database=DATABASE_ID

DATABASE_ID を、データベース ID または default に置き換えます。

出力は次のとおりです。

    appEngineIntegrationMode: ENABLED
    concurrencyMode: PESSIMISTIC
    createTime: '2021-03-24T17:02:35.234Z'
    deleteProtectionState: DELETE_PROTECTION_DISABLED
    earliestVersionTime: '2023-06-12T16:17:25.222474Z'
    etag: IIDayqOevv8CMNTvyNK4uv8C
    keyPrefix: s
    locationId: nam5
    name: projects/PROJECT_ID/databases/(default)
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: DATASTORE_MODE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

ここで

earliestVersionTime - 保存されている最も古い PITR データのタイムスタンプ。
pointInTimeRecoveryEnablement: PITR が有効になっている場合は、POINT_IN_TIME_RECOVERY_ENABLED が表示されます。PITR が無効になっている場合は、POINT_IN_TIME_RECOVERY_DISABLED が表示されるか、pointInTimeRecoveryEnablement フィールドが表示されません。
versionRetentionPeriod - PITR データが保持される期間（ミリ秒単位）。この値は、PITR が無効になっている場合は 1 時間、PITR が有効になっている場合は 7 日間になります。

PITR データを読み取る

PITR データを読み取るには、クライアントライブラリ、REST API メソッド、または FirestoreIO Apache Beam コネクタを使用します。

クライアントライブラリ

Java

PITR データを読み取るには、ReadOption クラスの readTime メソッドを使用する必要があります。ReadOnly トランザクションを使用して読み取りを行うことはできません。詳細については、ReadOption サンプルコードをご覧ください。

  Datastore datastore = ...
  Timestamp timestamp = ...

  // lookup
  Key key = ...
  Entity entity = datastore.get(key, ReadOption.readTime(timestamp));

  // runQuery
  Query<Entity> query = ...
  QueryResults<Entity> queryResult = datastore.run(query, ReadOption.readTime(timestamp));

  // runAggregationQuery
  AggregationQuery countAggregationQuery = ...
  Long count = getOnlyElement(datastore.runAggregation(countAggregationQuery, ReadOption.readTime(timestamp))).get("total_count");

readTime の例の一覧については、GitHub リポジトリをご覧ください。

Python

Datastore モードの Python SDK で readTime メソッドを使用して PITR 読み取りを使用するか、readTime で ReadOnly トランザクションを使用して読み取りを行います。

  from datetime import datetime, timezone

  read_time = datetime.now(tz=timezone.utc)

  key = …
  # read without PITR read time
  entity = client.get(key)

  # read with PITR read time
  entity = client.get(key, read_time=read_time)

  # PITR read using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      entity = client.get(key)

  query = client.query…
  # run query without PITR read time
  iterator = query.fetch()

  # run query with PITR read time
  iterator = query.fetch(read_time=read_time)

  # PITR read query using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      iterator = query.fetch()

readTime の例の一覧については、GitHub リポジトリをご覧ください。

REST API

PITR 読み取りは、Datastore モードの V1 読み取りメソッド（lookup、runQuery、runAggregationQuery）でサポートされています。

REST のメソッドを使用して読み取りを実行するには、次の方法があります。

読み取りメソッドリクエストで、サポートされている PITR タイムスタンプとして readOptions メソッドで readTime 値を渡します。PITR タイムスタンプには、過去 1 時間以内のマイクロ秒精度のタイムスタンプ、または過去 1 時間を超え、earliestVersionTime 以降の 1 分単位のタイムスタンプを指定できます。
複数の PITR 読み取りの ReadOnly トランザクションの一環として、readTime パラメータを BeginTransaction メソッドに使用します。

Apache Beam

Datastore モード IO Apache Beam コネクタを使用して、Dataflow で Datastore モードのデータベース内のエンティティを大規模に読み書きできます。

DatastoreV1.Read オブジェクトに withReadTime(Instant readTime) メソッドを指定します。DatastoreV1.Read オブジェクトを使用する後続の読み取りはすべて同じ readTime から読み取ります。

Java

次のコードは、PITR 読み取りに withReadTime メソッドを使用する方法を示しています。

  com.google.datastore.v1.Query query = ...
    Instant readTime = Instant.ofEpochSecond(1684098540L);

    DatastoreV1.Read read =
            DatastoreIO.v1()
                .read()
                .withProjectId(project)
                .withQuery(query)
                .withNamespace(namespace)
                .withReadTime(readTime);

    PCollection<Entity> entities = pipeline.apply(read);
    ...

withReadTime の例の完全な一覧については、GitHub リポジトリをご覧ください。

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]
```
ここで
- BUCKET_NAME_PATH - エクスポートファイルが保存される有効な Cloud Storage バケット（パス接頭辞は省略可能）。
- PITR_TIMESTAMP - 分単位の PITR タイムスタンプ（例: 2023-05-26T10:20:00.00Z または 2023-10-19T10:30:00.00-07:00）。
- COLLECTION_IDS - コレクション ID またはコレクショングループ ID のリスト（例: 'specific collection group1'、'specific collection group2'）。
- NAMESPACE_IDS - 名前空間 ID のリスト（例: 'customer'、'orders'）。
エンティティフィルタを使用して種類や名前空間の特定のサブセットをエクスポートすることもできます。

PITR データをエクスポートする前に、次の点に注意してください。
- RFC 3339 形式でタイムスタンプを指定しますたとえば、2023-05-26T10:20:00.00Z や 2023-10-19T10:30:00.00-07:00 です。
- タイムスタンプは、過去 1 時間以内（ただし earliestVersionTime 以降）の 1 分単位のタイムスタンプを指定する必要があります。指定したタイムスタンプにデータが存在しない場合は、エラーが発生します。指定された時刻が過去 1 時間以内であっても、タイムスタンプは 1 分単位で指定する必要があります。
- 失敗した PITR エクスポートについては課金されません。
データベースにインポートします。

すべてのエンティティのインポートの手順に沿って、エクスポートしたデータベースをインポートします。データベースにすでにエンティティが存在する場合は上書きされます。エンティティフィルタを使用して種類や名前空間の特定のサブセットをインポートすることもできます。

ポイントインタイム リカバリ（PITR）の使用

権限

必要な権限

準備

PITR を有効にする

コンソール

gcloud

保持期間と最短版の時間を取得する

コンソール

gcloud

PITR データを読み取る

クライアント ライブラリ

Java

Python

REST API

Apache Beam

Java

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

gcloud

ポイントインタイムリカバリ（PITR）の使用

クライアントライブラリ