ポイントインタイムリカバリ（PITR）の操作

このページでは、ポイントインタイムリカバリ（PITR）を使用して 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
PITR データのエクスポート: datastore.databases.export
PITR データのインポート: datastore.databases.import

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

始める前に

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

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

PITR を有効にする

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

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

Console

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 - firestore-native に設定します。

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

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

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

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

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

Console

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

[データベース] に移動
データベースのリストから、必要なデータベースを選択します。
ナビゲーションメニューで、[障害復旧] をクリックします。
[設定] セクションの [保持期間] と [最も古いバージョンの時刻] をメモします。
- 保持期間: Firestore がデータベースのすべてのバージョンのデータを保持する期間。この値は、PITR が無効になっている場合は 1 時間、PITR が有効になっている場合は 7 日間です。
- 最も古いバージョンの時刻: PITR 期間で古いバージョンのデータを読み取ることができる最も古いタイムスタンプ。この値は Firestore によって継続的に更新されますが、クエリが行われるとその時点で最新ではなくなります。この値を使用してデータを復元する場合、値がクエリされてから復元を行うまでの間に経過した時間を考慮する必要があります。
- ポイントインタイムリカバリ: 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: FIRESTORE_NATIVE
    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 データを読み取るには、ReadOnly トランザクションを使用する必要があります。読み取りで readTime を直接指定することはできません。詳細については、トランザクションとバッチ書き込みをご覧ください。

  Firestore firestore = …

  TransactionOptions options =
          TransactionOptions.createReadOnlyOptionsBuilder()
              .setReadTime(
                  com.google.protobuf.Timestamp.newBuilder()
                      .setSeconds(1684098540L)
                      .setNanos(0))
              .build();

  ApiFuture<Void> futureTransaction = firestore.runTransaction(
              transaction -> {
                // Does a snapshot read document lookup
                final DocumentSnapshot documentResult =
                    transaction.get(documentReference).get();

                // Executes a snapshot read query
                final QuerySnapshot queryResult =
                  transaction.get(query).get();
              },
              options);

  // Blocks on transaction to complete
  futureTransaction.get();

ノード

  const documentSnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(documentRef),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

  const querySnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(query),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
  )

REST API

PITR の読み取りは Firestore のすべての読み取りメソッドでサポートされています（get、list、batchGet、listCollectionIds、listDocuments、runQuery、runAggregationQuery、partitionQuery）。

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

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

Apache Beam

FirestoreIO Apache Beam コネクタを使用して、Dataflow で Firestore データベース内のドキュメントを大規模に読み書きできます。

PITR 読み取りは、FirestoreIO コネクタの次の読み取りメソッドでサポートされています。次の読み取りメソッドは、PITR 読み取りに使用できる withReadTime(@Nullable Instant readTime) メソッドをサポートしています。

Java

次のコードは、Dataflow パイプラインのコード例で一括読み取りまたは一括書き込みのオペレーションに使用できます。この例では、PITR の読み取りに withReadTime(@Nullable Instant readTime) メソッドを使用しています。

  Instant readTime = Instant.ofEpochSecond(1684098540L);

  PCollection<Document> documents =
      pipeline
          .apply(Create.of(collectionId))
          .apply(
              new FilterDocumentsQuery(
                  firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
          .apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
  ...

Dataflow パイプラインの readTime の例の一覧については、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 です。
- タイムスタンプは、過去 7 日間以内（ただし earliestVersionTime 以降）の 1 分単位のタイムスタンプを指定する必要があります。指定したタイムスタンプにデータが存在しない場合、エラーが発生します。指定した時刻が過去 1 時間以内であっても、タイムスタンプは 1 分単位で指定する必要があります。
- 失敗した PITR エクスポートについては課金されません。
データベースにインポートします。

すべてのドキュメントをインポートする手順に沿って、エクスポートしたデータベースをインポートします。データベースにすでにドキュメントが存在する場合は上書きされます。

ポイントインタイム リカバリ（PITR）の操作

権限

必要な権限

始める前に

PITR を有効にする

Console

gcloud

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

Console

gcloud

PITR データを読み取る

クライアント ライブラリ

Java

ノード

REST API

Apache Beam

Java

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

gcloud

ポイントインタイムリカバリ（PITR）の操作

クライアントライブラリ