ポイントインタイム リカバリ(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();
ノード
PITR データを読み取るには、ReadOnly
トランザクションを使用する必要があります。読み取りで readTime
を直接指定することはできません。詳細については、トランザクションとバッチ書き込みをご覧ください。
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)
メソッドをサポートしています。
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
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 エクスポートについては課金されません。
データベースにインポートします。
すべてのドキュメントをインポートする手順に沿って、エクスポートしたデータベースをインポートします。データベースにすでにドキュメントが存在する場合は上書きされます。