このページでは、ポイントインタイム リカバリ(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 を有効にするには:
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
- Datastore モードに設定します。
PITR を無効にするには、次のように gcloud firestore databases update
コマンドを使用します。
gcloud firestore databases update\
[--database=DATABASE_ID; default="(default)"]\
--no-enable-pitr
次のように置き換えます。
DATABASE_ID
- データベース ID または(default)に設定します。
保持期間と最短版の時間を取得する
Console
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 エクスポートについては課金されません。
データベースにインポートします。
すべてのエンティティのインポートの手順に沿って、エクスポートしたデータベースをインポートします。データベースにすでにエンティティが存在する場合は上書きされます。エンティティ フィルタを使用して種類や名前空間の特定のサブセットをインポートすることもできます。