Arbeiten mit Point-in-Time-Recovery (PITR)

Auf dieser Seite wird beschrieben, wie Sie Point-in-Time Recovery (PITR) verwenden, um Daten in Cloud Firestore aufzubewahren und wiederherzustellen.

Informationen zum Verständnis der PITR-Konzepte finden Sie unter Point-in-Time Recovery .

Berechtigungen

Um die Berechtigungen zu erhalten, die Sie zum Verwalten von PITR-Einstellungen benötigen, bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zu erteilen, in dem Sie PITR aktivieren möchten:

  • Besitzer des Cloud-Datenspeichers ( roles/datastore.owner )

Stellen Sie für benutzerdefinierte Rollen sicher, dass die folgenden Berechtigungen gewährt werden:

  • So aktivieren Sie PITR beim Erstellen einer Datenbank: datastore.databases.create
  • So aktualisieren Sie PITR-Einstellungen für eine vorhandene Datenbank: datastore.databases.update , datastore.databases.list
  • So führen Sie Lesevorgänge aus PITR-Daten durch: datastore.databases.get , datastore.entities.get , datastore.entities.list
  • So exportieren Sie PITR-Daten: datastore.databases.export
  • So importieren Sie PITR-Daten: datastore.databases.import

Bevor Sie beginnen

Beachten Sie die folgenden Punkte, bevor Sie PITR verwenden:

  • Sie können nicht unmittelbar nach der Aktivierung von PITR mit dem Lesen von sieben Tagen in der Vergangenheit beginnen.
  • Wenn Sie PITR beim Erstellen einer Datenbank aktivieren möchten, müssen Sie den Befehl gcloud firestore databases create verwenden. Die Aktivierung von PITR beim Erstellen einer Datenbank mit der GCP Console wird nicht unterstützt.
  • Cloud Firestore beginnt mit der Aufbewahrung von Versionen ab dem Zeitpunkt nach der Aktivierung von PITR.
  • Sie können PITR-Daten nicht im PITR-Fenster lesen, nachdem Sie PITR deaktiviert haben.
  • Wenn Sie PITR unmittelbar nach der Deaktivierung wieder aktivieren, sind die früheren PITR-Daten nicht mehr verfügbar. Alle PITR-Daten, die vor der Deaktivierung von PITR erstellt wurden, werden nach dem PITR-Ablaufdatum gelöscht.
  • Wenn Sie in der letzten Stunde versehentlich Daten gelöscht haben und PITR deaktiviert ist, können Sie Ihre Daten wiederherstellen, indem Sie PITR innerhalb einer Stunde nach dem Löschen aktivieren.
  • Jeder Lesevorgang für abgelaufene PITR-Daten schlägt fehl.

Aktivieren Sie PITR

Aktivieren Sie vor der Verwendung von PITR die Abrechnung für Ihr Google Cloud-Projekt . Nur Google Cloud-Projekte mit aktivierter Abrechnung können die PITR-Funktionalität nutzen.

So aktivieren Sie PITR für Ihre Datenbank:

Konsole

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Disaster Recovery .

  4. Klicken Sie auf Bearbeiten , um die Einstellungen zu bearbeiten.

  5. Aktivieren Sie das Kontrollkästchen Point-in-Time-Wiederherstellung aktivieren und klicken Sie dann auf Speichern .

Durch die Aktivierung von PITR würden Speicherkosten anfallen. Weitere Informationen finden Sie unter Preise .

Um PITR zu deaktivieren, deaktivieren Sie das Kontrollkästchen Point-in-Time-Wiederherstellung aktivieren auf der Seite Notfallwiederherstellung in der GCP-Konsole.

gcloud

Aktivieren Sie PITR während der Datenbankerstellung mit dem gcloud firestore databases create -Befehl wie folgt:

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

Ersetzen Sie die Werte wie folgt:

  • Location – Standort, an dem Sie Ihre Datenbank erstellen möchten.
  • DATABASE_ID – auf die Datenbank-ID oder (Standard) eingestellt.
  • TYPE – auf Firestore-nativ eingestellt.

Sie können PITR mit dem gcloud firestore databases update Befehl wie folgt deaktivieren:

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

Ersetzen Sie die Werte wie folgt:

  • DATABASE_ID – auf die Datenbank-ID oder (Standard) eingestellt.

Erhalten Sie den Aufbewahrungszeitraum und die früheste Versionszeit

Konsole

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Disaster Recovery .

  4. Beachten Sie im Abschnitt „Einstellungen“ den Aufbewahrungszeitraum und die Zeit der frühesten Version .

    • Aufbewahrungszeitraum : Der Zeitraum, in dem Cloud Firestore alle Datenversionen für die Datenbank aufbewahrt. Der Wert beträgt eine Stunde, wenn PITR deaktiviert ist, und sieben Tage, wenn PITR aktiviert ist.
    • Früheste Versionszeit : Der früheste Zeitstempel, zu dem ältere Versionen der Daten im PITR-Fenster gelesen werden können. Dieser Wert wird von Cloud Firestore kontinuierlich aktualisiert und veraltet, sobald er abgefragt wird. Wenn Sie diesen Wert zum Wiederherstellen von Daten verwenden, berücksichtigen Sie unbedingt die Zeit von der Abfrage des Werts bis zu dem Zeitpunkt, an dem Sie die Wiederherstellung starten.
    • Wiederherstellung zu einem bestimmten Zeitpunkt : Zeigt Enabled an, wenn PITR aktiviert ist. Wenn PITR deaktiviert ist, wird Disabled angezeigt.

gcloud

Führen Sie den Befehl „gcloud firestore Databases beschreiben“ wie folgt aus:

gcloud firestore databases describe --database=DATABASE_ID

Ersetzen Sie DATABASE_ID durch die Datenbank-ID oder default .

Hier ist die Ausgabe:

    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

Wo,

  • earliestVersionTime – Zeitstempel der frühesten gespeicherten PITR-Daten.
  • pointInTimeRecoveryEnablement : zeigt POINT_IN_TIME_RECOVERY_ENABLED an, wenn PITR aktiviert ist. Wenn PITR deaktiviert ist, wird entweder POINT_IN_TIME_RECOVERY_DISABLED angezeigt oder das Feld pointInTimeRecoveryEnablement wird möglicherweise nicht angezeigt.
  • versionRetentionPeriod – Zeitraum, für den PITR-Daten aufbewahrt werden, in Millisekunden. Der Wert kann eine Stunde betragen, wenn PITR deaktiviert ist, oder sieben Tage, wenn PITR aktiviert ist.

PITR-Daten lesen

Sie können PITR-Daten mithilfe der Clientbibliotheken, REST-API-Methoden oder des FirestoreIO Apache Beam-Connectors lesen.

Client-Bibliotheken

Java

Sie müssen die ReadOnly Transaktion verwenden, um PITR-Daten zu lesen. Sie können readTime nicht direkt in Lesevorgängen angeben. Weitere Informationen finden Sie unter Transaktionen und Batch-Schreibvorgänge .

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

Knoten

Sie müssen eine ReadOnly Transaktion verwenden, um PITR-Daten zu lesen. Sie können readTime nicht direkt in Lesevorgängen angeben. Weitere Informationen finden Sie unter Transaktionen und Batch-Schreibvorgänge .

  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-Lesevorgänge werden in allen Cloud Firestore-Lesemethoden unterstützt: get , list , batchGet , listCollectionIds , listDocuments , runQuery , runAggregationQuery und partitionQuery .

Um einen Lesevorgang mit den REST-Methoden durchzuführen, probieren Sie eine der folgenden Optionen aus:

  1. Übergeben Sie in Ihrer Lesemethodenanforderung den readTime Wert als unterstützten PITR-Zeitstempel in der readOptions Methode. Ein PITR-Zeitstempel kann entweder ein Zeitstempel mit Mikrosekundengenauigkeit innerhalb der letzten Stunde oder ein Zeitstempel mit einer ganzen Minute nach der letzten Stunde sein, jedoch nicht früher als die earliestVersionTime .

  2. Verwenden Sie den Parameter readTime zusammen mit der Methode BeginTransaction als Teil einer ReadOnly Transaktion für mehrere PITR-Lesevorgänge.

Apache Beam

Verwenden Sie den Cloud FirestoreIO Apache Beam-Connector, um mit Dataflow in großem Umfang Dokumente in einer Cloud Firestore-Datenbank zu lesen oder zu schreiben.

PITR-Lesevorgänge werden in der folgenden Lesemethode des Cloud FirestoreIO-Connectors unterstützt. Diese Lesemethoden unterstützen die Methode withReadTime(@Nullable Instant readTime) , die Sie für PITR-Lesevorgänge verwenden können:

Java

Der folgende Code kann mit dem Beispiel-Dataflow-Pipeline-Code für Massenlese- oder -schreibvorgänge verwendet werden. Das Beispiel verwendet die Methode withReadTime(@Nullable Instant readTime) für PITR-Lesevorgänge.

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

Eine vollständige Liste der readTime Beispiele in der Dataflow-Pipeline finden Sie im Github-Repository .

Export und Import von PITR-Daten

Mit dem Befehl gcloud firestore export können Sie Ihre Datenbank aus PITR-Daten in Cloud Storage exportieren. Sie können PITR-Daten exportieren, bei denen der Zeitstempel ein ganzer Minutenzeitstempel innerhalb der letzten sieben Tage ist, jedoch nicht früher als die earliestVersionTime . Wenn zum angegebenen Zeitstempel keine Daten mehr vorhanden sind, schlägt der Exportvorgang fehl.

Der PITR-Exportvorgang unterstützt alle Filter, einschließlich des Exports aller Dokumente und des Exports bestimmter Sammlungen.

  1. Exportieren Sie die Datenbank und geben Sie dabei als Parameter snapshot-time den gewünschten Wiederherstellungszeitstempel an.

    gcloud

    Führen Sie den folgenden Befehl aus, um die Datenbank in Ihren Bucket zu exportieren.

    gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP] \
    --collection-ids=[COLLECTION_IDS] \
    --namespace-ids=[NAMESPACE_IDS]

    Wo,

    • BUCKET_NAME_PATH – ein gültiger Cloud Storage-Bucket mit einem optionalen Pfadpräfix, in dem Exportdateien gespeichert werden.
    • PITR_TIMESTAMP – ein PITR-Zeitstempel in Minutenauflösung, zum Beispiel 2023-05-26T10:20:00.00Z oder 2023-10-19T10:30:00.00-07:00 .
    • COLLECTION_IDS – eine Liste von Sammlungs-IDs oder Sammlungsgruppen-IDs, zum Beispiel 'specific collection group1' , 'specific collection group2' .
    • NAMESPACE_IDS – eine Liste von Namespace-IDs, zum Beispiel 'customer' , 'orders' .

    Beachten Sie die folgenden Punkte, bevor Sie PITR-Daten exportieren:

    • Geben Sie den Zeitstempel im RFC 3339-Format an. Zum Beispiel 2023-05-26T10:20:00.00Z oder 2023-10-19T10:30:00.00-07:00 .
    • Stellen Sie sicher, dass der von Ihnen angegebene Zeitstempel ein ganzer Minutenzeitstempel der letzten sieben Tage ist, jedoch nicht früher als die earliestVersionTime . Wenn zum angegebenen Zeitstempel keine Daten mehr vorhanden sind, wird ein Fehler generiert. Der Zeitstempel muss eine ganze Minute betragen, auch wenn die angegebene Zeit innerhalb der letzten Stunde liegt.
    • Für einen fehlgeschlagenen PITR-Export werden Ihnen keine Kosten berechnet.

  2. In eine Datenbank importieren.

    Führen Sie die Schritte unter „Alle Dokumente importieren“ aus, um Ihre exportierte Datenbank zu importieren. Wenn in Ihrer Datenbank bereits ein Dokument vorhanden ist, wird es überschrieben.