このページは Cloud Translation API によって翻訳されました。

ポイントインタイムリカバリ（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
データベースのクローンを作成するには: datastore.databases.clone

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

始める前に

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 を有効にするには:

コンソール

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

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

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

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

gcloud

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

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --type=firestore-native\
  --enable-pitr

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

LOCATION - データベースを作成するロケーション。
DATABASE_ID - データベース ID に設定します。

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

gcloud firestore databases update\
  --database=DATABASE_ID\
  --no-enable-pitr

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

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

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

コンソール

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/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

ここで

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 リポジトリをご覧ください。

データベースからクローンを作成する

選択したタイムスタンプの既存のデータベースを新しいデータベースにクローン作成できます。

クローン作成されたデータベースは、ソースデータベースと同じロケーションに作成される新しいデータベースです。

クローンを作成するために、Firestore はソースデータベースのポイントインタイムリカバリ（PITR）データを使用します。クローンデータベースには、すべてのデータとインデックスが含まれます。
デフォルトでは、クローン作成されたデータベースは、Google のデフォルトの暗号化または CMEK 暗号化を使用して、ソースデータベースと同じ方法で暗号化されます。別の暗号化タイプを指定することも、CMEK 暗号化に別の鍵を使用することもできます。
タイムスタンプは 1 分単位で、PITR 期間で定義した期間内の過去の時点を指定します。
- データベースで PITR が有効になっている場合は、過去 7 日間の任意の分を選択します（PITR が 7 日前より短い時点で有効になった場合は、それより短い期間になります）。
- PITR が有効になっていない場合は、過去 1 時間の任意の分を選択できます。
- 選択できる最も古いタイムスタンプは、データベースの説明で確認できます。

コンソール

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

[データベース] に移動
クローンを作成するデータベースのテーブル行にある [さらに表示] をクリックします。[クローン] をクリックします。[クローンを作成] ダイアログが表示されます。
[クローンを作成] ダイアログで、データベースのクローンを作成するためのパラメータを指定します。
1. [クローンの ID を設定] フィールドに、新しいクローンデータベースのデータベース ID を入力します。このデータベース ID を、既存のデータベースに関連付けることはできません。
2. [クローン元] フィールドで、クローニングに使用する時点を選択します。選択した時間は、分単位の PITR タイムスタンプに対応しています。
[クローンを作成] をクリックします。

gcloud

gcloud alpha firestore databases clone コマンドを使用して、データベースのクローンを作成します。

gcloud alpha firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

以下を置き換えます。

SOURCE_DATABASE: クローンを作成する既存のデータベースのデータベース名。名前の形式は projects/PROJECT_ID/databases/SOURCE_DATABASE_ID です。
PITR_TIMESTAMP: RFC 3339 形式の PITR タイムスタンプ（分単位）。たとえば、2025-06-01T10:20:00.00Z や 2025-06-01T10:30:00.00-07:00 です。
DESTINATION_DATABASE_ID: クローン作成された新しいデータベースのデータベース ID。このデータベース ID を、既存のデータベースに関連付けることはできません。

例:

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='projects/example-project/databases/example-dest-db'

クローン作成されたデータベースの暗号化構成を変更する

デフォルトでは、クローン作成されたデータベースには、ソースデータベースと同じ暗号化構成が設定されます。暗号化構成を変更するには、--encryption-type 引数を使用します。

（デフォルト）use-source-encryption: ソースデータベースと同じ暗号化構成を使用します。
google-default-encryption: Google のデフォルトの暗号化を使用
customer-managed-encryption: CMEK 暗号化を使用します。--kms-key-name 引数でキー ID を指定します。

次の例は、クローン作成されたデータベースの CMEK 暗号化を構成する方法を示しています。

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='projects/example-project/databases/example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

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 を有効にする

コンソール

gcloud

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

コンソール

gcloud

PITR データを読み取る

クライアント ライブラリ

Java

ノード

REST API

Apache Beam

Java

データベースからクローンを作成する

コンソール

gcloud

クローン作成されたデータベースの暗号化構成を変更する

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

gcloud

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

クライアントライブラリ