Praca z odtwarzaniem do punktu w czasie (PITR)

Na tej stronie opisano, jak używać odzyskiwania do punktu w czasie (PITR) do przechowywania i odzyskiwania danych w Cloud Firestore.

Aby zrozumieć koncepcje PITR, zobacz Odzyskiwanie do punktu w czasie .

Uprawnienia

Aby uzyskać uprawnienia potrzebne do zarządzania ustawieniami PITR, poproś administratora o przyznanie Ci następujących ról IAM w projekcie, w którym chcesz włączyć PITR:

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

W przypadku ról niestandardowych upewnij się, że przyznano następujące uprawnienia:

  • Aby włączyć PITR podczas tworzenia bazy danych: datastore.databases.create
  • Aby zaktualizować ustawienia PITR w istniejącej bazie danych: datastore.databases.update , datastore.databases.list
  • Aby wykonać odczyty z 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 używać PITR, zwróć uwagę na następujące punkty:

  • Nie możesz rozpocząć czytania od siedmiu dni wstecz natychmiast po włączeniu PITR.
  • Jeśli chcesz włączyć PITR podczas tworzenia bazy danych, musisz użyć polecenia gcloud firestore databases create . Włączenie PITR podczas tworzenia bazy danych przy użyciu konsoli GCP nie jest obsługiwane.
  • Cloud Firestore zaczyna przechowywać wersje od momentu włączenia PITR.
  • Po wyłączeniu PITR nie można odczytać danych PITR w oknie PITR.
  • Jeśli ponownie włączysz PITR natychmiast po jego wyłączeniu, poprzednie dane PITR nie będą już dostępne. Wszelkie dane PITR utworzone przed wyłączeniem PITR zostaną usunięte po dacie wygaśnięcia PITR.
  • Jeśli przypadkowo usunąłeś dane w ciągu ostatniej godziny, a PITR jest wyłączony, możesz przywrócić swoje dane, włączając PITR w ciągu godziny od usunięcia.
  • Jakikolwiek odczyt przeterminowanych danych PITR kończy się niepowodzeniem.

Włącz PITR

Przed użyciem PITR włącz rozliczenia dla swojego projektu Google Cloud . Tylko projekty Google Cloud z włączonymi rozliczeniami mogą korzystać z funkcjonalności PITR.

Aby włączyć PITR dla swojej bazy danych:

Konsola

  1. W konsoli Google Cloud Platform przejdź do strony Bazy danych .

    Przejdź do Baz danych

  2. Wybierz żądaną bazę danych z listy baz danych.

  3. W menu nawigacyjnym kliknij opcję Odzyskiwanie po awarii .

  4. Kliknij Edytuj, aby edytować ustawienia.

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

Włączenie PITR wiązałoby się z kosztami przechowywania. Aby uzyskać więcej informacji, zobacz Cennik .

Aby wyłączyć funkcję PITR, usuń zaznaczenie pola wyboru Włącz odzyskiwanie do określonego momentu na stronie Odzyskiwanie po awarii w konsoli GCP.

gcloud

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

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

Zamień wartości w następujący sposób:

  • Location - lokalizacja, w której chcesz utworzyć bazę danych.
  • DATABASE_ID - ustawiony na identyfikator bazy danych lub (domyślnie).
  • TYPE — ustawiony na natywny dla Firestore.

Możesz wyłączyć PITR za pomocą polecenia gcloud firestore databases update w następujący sposób:

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

Zamień wartości w następujący sposób:

  • DATABASE_ID - ustawiony na identyfikator bazy danych lub (domyślnie).

Uzyskaj okres przechowywania i godzinę najwcześniejszej wersji

Konsola

  1. W konsoli Google Cloud Platform przejdź do strony Bazy danych .

    Przejdź do Baz danych

  2. Wybierz żądaną bazę danych z listy baz danych.

  3. W menu nawigacyjnym kliknij opcję Odzyskiwanie po awarii .

  4. W sekcji Ustawienia zanotuj Okres przechowywania i Czas najwcześniejszej wersji .

    • Okres przechowywania : okres, w którym Cloud Firestore przechowuje wszystkie wersje danych w bazie danych. Wartość wynosi jedną godzinę, gdy funkcja PITR jest wyłączona, i siedem dni, gdy funkcja PITR jest włączona.
    • Czas najwcześniejszej wersji : najwcześniejszy znacznik czasu, w którym starsze wersje danych można odczytać w oknie PITR. Ta wartość jest stale aktualizowana przez Cloud Firestore i staje się nieaktualna w momencie zapytania. Jeśli używasz tej wartości do odzyskiwania danych, pamiętaj o uwzględnieniu czasu od momentu sprawdzenia wartości do momentu rozpoczęcia odzyskiwania.
    • Odzyskiwanie do punktu w czasie : wyświetla Enabled , jeśli funkcja PITR jest włączona. Jeśli opcja PITR jest wyłączona, wyświetli się Disabled .

gcloud

Uruchom polecenie gcloud Firestore Databases opis w następujący sposób:

gcloud firestore databases describe --database=DATABASE_ID

Zamień DATABASE_ID na identyfikator bazy danych lub default .

Oto dane wyjściowe:

    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 — znacznik czasu najwcześniejszych zapisanych danych PITR.
  • pointInTimeRecoveryEnablement : pokazuje POINT_IN_TIME_RECOVERY_ENABLED , jeśli PITR jest włączony. Jeśli funkcja PITR jest wyłączona, zostanie wyświetlony komunikat POINT_IN_TIME_RECOVERY_DISABLED lub pole pointInTimeRecoveryEnablement może nie być wyświetlane.
  • versionRetentionPeriod - okres czasu, przez który dane PITR są przechowywane w milisekundach. Wartość może wynosić jedną godzinę, gdy funkcja PITR jest wyłączona, lub siedem dni, jeśli funkcja PITR jest włączona.

Przeczytaj dane PITR

Dane PITR można odczytać za pomocą bibliotek klienckich, metod REST API lub łącznika FirestoreIO Apache Beam.

Biblioteki klienta

Jawa

Aby odczytać dane PITR, należy użyć transakcji ReadOnly . Nie można bezpośrednio określić readTime w odczytach. Aby uzyskać więcej informacji, zobacz Transakcje i zapisy wsadowe .

  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 odczytać dane PITR, należy użyć transakcji ReadOnly . Nie można bezpośrednio określić readTime w odczytach. Aby uzyskać więcej informacji, zobacz Transakcje i zapisy wsadowe .

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

API RESTOWE

Odczyty PITR są obsługiwane we wszystkich metodach odczytu Cloud Firestore, którymi są get , list , BatchGet , listCollectionIds , listDocuments , runQuery , runAggregationQuery i PartitionQuery .

Aby wykonać odczyt przy użyciu metod REST, wypróbuj jedną z następujących opcji:

  1. W żądaniu metody read przekaż wartość readTime jako obsługiwany znacznik czasu PITR w metodzie readOptions . Znacznik czasu PITR może być albo znacznikiem czasu z dokładnością do mikrosekundy w ciągu ostatniej godziny, albo znacznikiem czasu obejmującym całą minutę poza ostatnią godziną, ale nie wcześniej niż earliestVersionTime .

  2. Użyj parametru readTime razem z metodą BeginTransaction w ramach transakcji ReadOnly dla wielu odczytów PITR.

Promień Apacza

Użyj łącznika Cloud FirestoreIO Apache Beam, aby czytać lub zapisywać dokumenty w bazie danych Cloud Firestore na dużą skalę za pomocą Dataflow.

Odczyty PITR są obsługiwane w następującej metodzie odczytu łącznika Cloud FirestoreIO. Te metody odczytu obsługują metodę withReadTime(@Nullable Instant readTime) , której możesz używać do odczytów PITR:

Jawa

Poniższego kodu można użyć z przykładowym kodem potoku Dataflow dla zbiorczych operacji odczytu lub zapisu. W przykładzie zastosowano metodę 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 .

Eksport i import z danych PITR

Możesz wyeksportować swoją bazę danych do Cloud Storage z danych PITR za pomocą polecenia gcloud firestore export . Możesz wyeksportować dane PITR, gdzie sygnatura czasowa to pełny minutowy sygnatura czasowa z ostatnich siedmiu dni, ale nie wcześniejsza niż earliestVersionTime . Jeśli w określonym znaczniku czasu dane już nie istnieją, operacja eksportu zakończy się niepowodzeniem.

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

  1. Wyeksportuj bazę danych, określając parametr snapshot-time jako żądany znacznik czasu odzyskiwania.

    gcloud

    Uruchom następujące polecenie, aby wyeksportować bazę danych do swojego segmentu.

    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 przedrostkiem ścieżki, w którym przechowywane są pliki eksportu.
    • PITR_TIMESTAMP - znacznik czasu PITR z dokładnością do minuty, na przykład 2023-05-26T10:20:00.00Z lub 2023-10-19T10:30:00.00-07:00 .
    • COLLECTION_IDS - lista identyfikatorów kolekcji lub identyfikatorów grup kolekcji, np 'specific collection group1' , 'specific collection group2' .
    • NAMESPACE_IDS - lista identyfikatorów przestrzeni nazw, np 'customer' , 'orders' .

    Przed eksportowaniem danych PITR należy zwrócić uwagę na następujące kwestie:

    • Określ znacznik czasu 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 podany znacznik czasu to pełny minutowy znacznik czasu z ostatnich siedmiu dni, ale nie wcześniejszy niż earliestVersionTime . Jeśli w określonym znaczniku czasu dane już nie istnieją, generowany jest błąd. Znacznik czasu musi oznaczać całą minutę, nawet jeśli określony czas przypada w ciągu ostatniej godziny.
    • Nie pobierzesz opłaty za nieudany eksport PITR.

  2. Importuj do bazy danych.

    Aby zaimportować wyeksportowaną bazę danych, wykonaj czynności opisane w artykule Importuj wszystkie dokumenty . Jeżeli w Twojej bazie danych istnieje już jakiś dokument, zostanie on nadpisany.