Praca z odzyskiwaniem do określonego momentu

Na tej stronie dowiesz się, jak korzystać z odzyskiwania do określonego momentu (PITR) do przechowywania i przywracania danych w Cloud Firestore.

Aby zapoznać się z pojęciami dotyczącymi odzyskiwania do określonego momentu, zapoznaj się z artykułem Odzyskiwanie do określonego momentu.

Uprawnienia

Aby uzyskać uprawnienia potrzebne do zarządzania ustawieniami odzyskiwania do określonego momentu, poproś administratora o przypisanie Ci tych ról uprawnień w projekcie, w którym chcesz włączyć tę funkcję:

  • Właściciel Cloud Datastore (roles/datastore.owner)

W przypadku ról niestandardowych przyznaj te uprawnienia:

  • Aby włączyć PITR podczas tworzenia bazy danych: datastore.databases.create
  • Aby zaktualizować ustawienia odzyskiwania do określonego momentu w istniejącej bazie danych: datastore.databases.update,datastore.databases.list
  • Aby przeprowadzać odczyty danych PITR: datastore.databases.get,datastore.entities.get,datastore.entities.list
  • Aby wyeksportować dane PITR: datastore.databases.export
  • Aby zaimportować dane PITR: datastore.databases.import

Zanim zaczniesz

Zanim zaczniesz korzystać z odzyskiwania do określonego momentu, weź pod uwagę te informacje:

  • Bezpośrednio po włączeniu odzyskiwania do określonego momentu nie można zacząć czytać z ostatnich 7 dni.
  • Jeśli chcesz włączyć PITR podczas tworzenia bazy danych, musisz użyć polecenia gcloud firestore databases create. Włączanie PITR podczas tworzenia bazy danych za pomocą konsoli GCP nie jest obsługiwane.
  • Cloud Firestore zaczyna przechowywać wersje od momentu włączenia PITR.
  • Po wyłączeniu tej funkcji nie można odczytać danych odzyskiwania do określonego momentu w oknie odzyskiwania do niej.
  • Jeśli włączysz funkcję odzyskiwania do określonego momentu natychmiast po jej wyłączeniu, wcześniejsze dane dotyczące odzyskiwania do określonego momentu nie będą już dostępne. Wszystkie dane PITR utworzone przed wyłączeniem odzyskiwania do określonego momentu zostaną usunięte po dacie wygaśnięcia PITR.
  • Jeśli dane zostały przypadkowo usunięte w ciągu ostatniej godziny i wyłączona jest funkcja odzyskiwania danych, możesz przywrócić dane, włączając tę funkcję w ciągu godziny od usunięcia.
  • Każdy odczyt przeprowadzony na wygasłych danych PITR kończy się niepowodzeniem.

Włącz PITR

Zanim zaczniesz używać odzyskiwania do określonego momentu, włącz płatności w projekcie Google Cloud. Z funkcji odzyskiwania do odzyskiwania konta mogą korzystać tylko w projektach Google Cloud, w których włączono płatności.

Aby włączyć PITR w bazie danych:

Konsola

  1. W konsoli Google Cloud Platform otwórz stronę Bazy danych.

    Otwórz Bazy danych

  2. Wybierz wymaganą bazę danych z listy baz danych.

  3. W menu nawigacyjnym kliknij Odtwarzanie awaryjne.

  4. Aby zmienić ustawienia, kliknij Edytuj.

  5. Zaznacz pole wyboru Włącz odzyskiwanie do określonego momentu, a następnie kliknij Zapisz.

Włączenie PITR spowoduje naliczanie opłat za miejsce na dane. Więcej informacji znajdziesz w sekcji Ceny.

Aby wyłączyć odzyskiwanie do określonego momentu, odznacz pole wyboru Włącz odzyskiwanie do określonego momentu na stronie Odtwarzanie awaryjne w konsoli GCP.

gcloud

Włącz PITR podczas tworzenia bazy danych za pomocą polecenia gcloud firestore databases create w ten sposób:

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

Zastąp te wartości w ten sposób:

  • Location – lokalizacja, w której chcesz utworzyć bazę danych.
  • DATABASE_ID – ustaw identyfikator bazy danych lub wartość (domyślnie).
  • TYPE – ustawiono na tryb natywny w firestore.

Aby wyłączyć PITR, użyj polecenia gcloud firestore databases update w ten sposób:

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

Zastąp te wartości w ten sposób:

  • DATABASE_ID – ustaw identyfikator bazy danych lub wartość (domyślnie).

Pobieranie okresu przechowywania i czasu najwcześniejszej wersji

Konsola

  1. W konsoli Google Cloud Platform otwórz stronę Bazy danych.

    Otwórz Bazy danych

  2. Wybierz wymaganą bazę danych z listy baz danych.

  3. W menu nawigacyjnym kliknij Odtwarzanie awaryjne.

  4. W sekcji Ustawienia zwróć uwagę na pola Okres przechowywania i Czas najwcześniejszej wersji.

    • Okres przechowywania: okres, w którym Cloud Firestore przechowuje wszystkie wersje danych w bazie danych. Wartość wynosi 1 godzinę przy wyłączonym narzędziu PTR i 7 dniach, gdy jest on włączony.
    • Czas najwcześniejszej wersji: najwcześniejsza sygnatura czasowa, w której można odczytać starsze wersje danych w oknie PITR. Ta wartość jest stale aktualizowana przez Cloud Firestore i staje się nieaktualna w chwili wykonania zapytania. Jeśli używasz tej wartości do odzyskiwania danych, pamiętaj, aby uwzględnić czas od momentu wysłania zapytania o wartość do momentu rozpoczęcia przywracania.
    • Odzyskiwanie do określonego momentu: pokazuje Enabled, jeśli włączono odzyskiwania do określonego momentu. Jeśli PITR jest wyłączone, zobaczysz Disabled.

gcloud

Uruchom polecenie gcloud Firestore databasesscribe w ten sposób:

gcloud firestore databases describe --database=DATABASE_ID

Zastąp DATABASE_ID identyfikatorem bazy danych lub default.

Wyniki będą wyglądać tak:

    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

Gdzie?

  • earliestVersionTime – sygnatura czasowa najstarszych przechowywanych danych PITR.
  • pointInTimeRecoveryEnablement: pokazuje wartość POINT_IN_TIME_RECOVERY_ENABLED, jeśli włączona jest funkcja odzyskiwania do określonego momentu. Jeśli funkcja odzyskiwania do określonego momentu jest wyłączona, zobaczysz POINT_IN_TIME_RECOVERY_DISABLED lub pole pointInTimeRecoveryEnablement może nie być wyświetlane.
  • versionRetentionPeriod – okres, przez jaki dane o PITR są przechowywane w milisekundach. Wartość może wynosić 1 godzinę, gdy klucz odzyskiwania jest wyłączony, lub 7 dni, jeśli jest włączony.

Odczytywanie danych odzyskiwania do określonego momentu

Dane PITR możesz odczytywać za pomocą bibliotek klienta, metod interfejsu API REST lub oprogramowania sprzęgającego FirestoreIO Apache Beam.

Biblioteki klienta

Java

Aby odczytywać dane PITR, musisz używać transakcji ReadOnly. Nie możesz bezpośrednio określać elementu readTime w odczytach. Więcej informacji znajdziesz w artykule Transakcje i zapisy zbiorcze.

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

Węzeł

Aby odczytywać dane PITR, musisz użyć transakcji ReadOnly. Nie możesz bezpośrednio określać elementu readTime w odczytach. Więcej informacji znajdziesz w artykule Transakcje i zapisy zbiorcze.

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

Interfejs API typu REST

Odczyty za pomocą PITR są obsługiwane we wszystkich metodach odczytu Cloud Firestore: get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery i partitionQuery.

Aby wykonać odczyt przy użyciu metod REST, wypróbuj jedną z tych opcji:

  1. W żądaniu metody odczytu przekaż wartość readTime jako obsługiwaną sygnaturę czasową PITR w metodzie readOptions. Sygnatura czasowa PITR może być albo mikrosekundową, precyzyjną sygnaturą czasową w ciągu ostatniej godziny, albo sygnaturą czasową całej minuty poza ostatnią godziną, ale nie wcześniej niż earliestVersionTime.

  2. Użyj parametru readTime w połączeniu z metodą BeginTransaction w ramach transakcji ReadOnly na potrzeby wielu odczytów PITR.

Apache Beam

Użycie oprogramowania sprzęgającego Cloud FirestoreIO Apache Beam do odczytywania i zapisywania dokumentów w bazie danych Cloud Firestore na dużą skalę za pomocą Dataflow.

Odczyty za pomocą PITR są obsługiwane w poniższej metodzie odczytu oprogramowania sprzęgającego Cloud FirestoreIO. Te metody odczytu obsługują metodę withReadTime(@Nullable Instant readTime), której możesz używać w przypadku odczytu PITR:

Java

Ten kod może być używany z przykładowym kodem potoku Dataflow do zbiorczych operacji odczytu lub zapisu. W przykładzie użyto metody withReadTime(@Nullable Instant readTime) do odczytów PITR.

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

Pełną listę przykładów readTime w potoku Dataflow znajdziesz w repozytorium GitHub.

Eksportowanie i importowanie danych PITR

Możesz wyeksportować bazę danych do Cloud Storage z danych PITR za pomocą polecenia gcloud firestore export. Możesz eksportować dane o PITR, gdzie sygnatura czasowa to pełna minuta z ostatnich 7 dni, ale nie wcześniej niż earliestVersionTime. Jeśli w podanej sygnaturze czasowej nie ma już danych, operacja eksportu się nie powiedzie.

Operacja eksportu PITR obsługuje wszystkie filtry, w tym eksport wszystkich dokumentów i określone zbiory.

  1. Wyeksportuj bazę danych, określając parametr snapshot-time do żądanej sygnatury czasowej przywracania.

    gcloud

    Aby wyeksportować bazę danych do zasobnika, uruchom to polecenie.

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

    Gdzie,

    • BUCKET_NAME_PATH – prawidłowy zasobnik Cloud Storage z opcjonalnym prefiksem ścieżki do miejsca, w którym są przechowywane pliki eksportu.
    • PITR_TIMESTAMP – sygnatura czasowa PITR z dokładnością co do minuty, np. 2023-05-26T10:20:00.00Z lub 2023-10-19T10:30:00.00-07:00.
    • COLLECTION_IDS – lista identyfikatorów kolekcji lub grup kolekcji, np. 'specific collection group1','specific collection group2'.
    • NAMESPACE_IDS – lista identyfikatorów przestrzeni nazw, na przykład 'customer','orders'.

    Przed wyeksportowaniem danych PITR weź pod uwagę te informacje:

    • Podaj sygnaturę czasową w formacie RFC 3339. na przykład 2023-05-26T10:20:00.00Z lub 2023-10-19T10:30:00.00-07:00.
    • Upewnij się, że podana sygnatura czasowa to pełna minuta z ostatnich 7 dni, ale nie wcześniejsza niż earliestVersionTime. Jeśli dane już nie istnieją w podanej sygnaturze czasowej, zostanie wygenerowany błąd. Sygnatura czasowa musi zawierać pełną minutę, nawet jeśli podany czas przypada w ciągu ostatniej godziny.
    • Nie obciążymy Cię płatnością za nieudany eksport PITR.

  2. Import do bazy danych.

    Aby zaimportować wyeksportowaną bazę danych, wykonaj czynności opisane w artykule Importowanie wszystkich dokumentów. Jeśli którykolwiek dokument istnieje już w bazie danych, zostanie zastąpiony.