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

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

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

権限

PITR 設定を管理するために必要な権限を取得するには、PITR を有効にするプロジェクトに対して次の IAM ロールを付与するよう管理者に依頼します。

• Cloud Datastore オーナー（roles/datastore.owner）

カスタムロールの場合は、次の権限を付与してください。

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

PITR を有効にする

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

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

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

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

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

gcloud firestore databases describe --database=DATABASE_ID

    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/DATABASE_ID
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

PITR データを読み取る

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

  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)}
  )

  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())
  ...

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

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

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

1. 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 エクスポートについては課金されません。

2. データベースにインポートします。

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