Praca z odzyskiwaniem do określonego momentu (PITR)

Na tej stronie opisujemy, jak używać funkcji odzyskiwania do określonego momentu (PITR) do przechowywania i odzyskiwania danych w Cloud Firestore.

Aby poznać pojęcia związane z odzyskiwaniem do określonego momentu, przeczytaj artykuł Odzyskiwanie do określonego momentu.

Uprawnienia

Aby uzyskać uprawnienia potrzebne do zarządzania ustawieniami PITR, poproś administratora o przypisanie Ci tych ról uprawnień 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 są przyznane te 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 odczytać dane z 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 PITR, weź pod uwagę te informacje:

  • Po włączeniu PITR nie możesz zacząć czytać od 7 dni wstecz.
  • 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 Google Cloud nie jest obsługiwane.
  • Cloud Firestore zaczyna przechowywać wersje od momentu włączenia odzyskiwania do określonego momentu.
  • Po wyłączeniu PITR nie można odczytać danych PITR w oknie PITR.
  • Jeśli PITR zostanie ponownie włączony bezpośrednio po wyłączeniu, poprzednie dane PITR nie będą już dostępne. Wszystkie dane PITR utworzone przed wyłączeniem PITR zostaną usunięte po dacie wygaśnięcia PITR.
  • Jeśli przypadkowo usuniesz dane w ciągu ostatniej godziny, a funkcja PITR jest wyłączona, możesz je przywrócić, włączając ją w ciągu 1 godziny od usunięcia.
  • Każde odczytanie wykonane na podstawie wygasłych danych PITR kończy się niepowodzeniem.

Włączanie odzyskiwania do określonego momentu

Zanim użyjesz PITR, włącz płatności za projekt Google Cloud. Z funkcji PITR mogą korzystać tylko projekty Google Cloud z włączonymi płatnościami.

Aby włączyć odzyskiwanie do określonego momentu w bazie danych:

Konsola

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

    Otwórz Bazy danych

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

  3. W menu nawigacyjnym kliknij Odzyskiwanie po katastrofie.

  4. Aby edytować ustawienia, kliknij Edytuj.

  5. Zaznacz pole wyboru Włącz punktowe przywracanie, a następnie kliknij Zapisz.

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

Aby wyłączyć PITR, odznacz pole wyboru Włącz odzyskiwanie do określonego momentu na stronie Odzyskiwanie po awarii w konsoli Google Cloud.

gcloud

Aby włączyć PITR podczas tworzenia bazy danych, użyj 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 wartości w ten sposób:

  • LOCATION – lokalizacja, w której chcesz utworzyć bazę danych.
  • DATABASE_ID – ustaw jako identyfikator bazy danych lub (domyślnie).
  • TYPE – ustaw na „firestore-native”.

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

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

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

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

Pobieranie okresu przechowywania i czasu najwcześniejszej wersji

Konsola

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

    Otwórz Bazy danych

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

  3. W menu nawigacyjnym kliknij Odzyskiwanie po katastrofie.

  4. W sekcji Ustawienia zwróć uwagę na okres przechowywania i najwcześniejszy czas wersji.

    • Okres przechowywania: okres, w którym Cloud Firestore przechowuje wszystkie wersje danych bazy danych. Gdy PITR jest wyłączone, wartość wynosi 1 godzinę, a gdy jest włączone – 7 dni.
    • Czas najstarszej wersji: najstarsza sygnatura czasowa, w której można odczytać starsze wersje danych w oknie PITR. Ta wartość jest stale aktualizowana (Cloud Firestore) i staje się nieaktualna w momencie, gdy zostanie zapytana. Jeśli używasz tej wartości do odzyskiwania danych, uwzględnij czas od momentu zapytania o wartość do momentu zainicjowania odzyskiwania.
    • Odzyskiwanie do określonego momentu: jeśli opcja PITR jest włączona, wyświetla się Enabled. Jeśli PITR jest wyłączony, zobaczyszDisabled.

gcloud

Uruchom polecenie gcloud firestore databases describe w ten sposób:

gcloud firestore databases describe --database=DATABASE_ID

Zastąp DATABASE_ID identyfikatorem bazy danych lub '(default)'.

Oto wynik:

    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/DATABASE_ID
    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 zapisanych danych PITR.
  • pointInTimeRecoveryEnablement: jeśli PITR jest włączony, wyświetla POINT_IN_TIME_RECOVERY_ENABLED. Jeśli zasada PITR jest wyłączona, zobaczysz pole POINT_IN_TIME_RECOVERY_DISABLED lub pole pointInTimeRecoveryEnablement może się nie wyświetlać.
  • versionRetentionPeriod: okres przechowywania danych PITR w milisekundach. Wartość może wynosić 1 godzinę, gdy PITR jest wyłączony, lub 7 dni, gdy jest włączony.

Odczytywanie danych PITR

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

Biblioteki klienta

Java

Aby odczytać dane PITR, musisz użyć transakcji ReadOnly. Nie możesz bezpośrednio określać wartości readTime w czytaniach. Więcej informacji znajdziesz w artykule Transakcje i zbiorowe zapisy.

  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, musisz użyć transakcji ReadOnly. Nie możesz bezpośrednio określać wartości readTime w czytaniach. Więcej informacji znajdziesz w artykule Transakcje i zbiorowe zapisy.

  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 PITR są obsługiwane we wszystkich metodach odczytu Cloud Firestore, czyli get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery i partitionQuery.

Aby wykonać operację odczytu za pomocą metod REST, użyj jednej z tych opcji:

  1. W żądaniu metody odczytu prześlij wartość readTime jako obsługiwany sygnaturą czasu PITR w metodzie readOptions. Sygnatura czasowa PITR może być sygnaturą czasową z dokładnością do mikrosekund w ciągu ostatniej godziny lub sygnaturą czasową z dokładnością do minuty po ostatniej godzinie, ale nie wcześniej niż earliestVersionTime.

  2. Aby odczytać wiele wartości PITR, użyj parametru readTime razem z metodą BeginTransaction w ramach transakcji ReadOnly.

Apache Beam

Użyj oprogramowania sprzęgającego Cloud FirestoreIO Apache Beam, aby odczytywać i zapisywać dokumenty w bazie danych Cloud Firestore na dużą skalę za pomocą Dataflow.

Czytanie PITR jest obsługiwane w ramach tej metody odczytu z interfejsu Cloud FirestoreIO. Te metody odczytu obsługują metodę withReadTime(@Nullable Instant readTime), której możesz używać do odczytu PITR:

Java

Poniższy kod można używać z przykładowym kodem potoku Dataflow do operacji zbiorczego odczytu lub zapisu. W tym przykładzie do odczytu PITR użyto metody 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())
  ...

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

Eksportowanie i importowanie danych z PITR

Możesz wyeksportować bazę danych do pliku Cloud Storage z danych PITR za pomocą polecenia gcloud firestore export. Dane PITR można eksportować, jeśli sygnatura czasowa jest sygnaturą minutową z ostatnich 7 dni, ale nie wcześniejszą niż earliestVersionTime. Jeśli dane nie istnieją już w określonym stempelu czasowym, operacja eksportu kończy się niepowodzeniem.

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

  1. Wyeksportuj bazę danych, podając parametr snapshot-time jako pożądaną sygnaturę czasową 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 zasób Cloud Storage z opcjonalnym prefiksem ścieżki, w którym są przechowywane pliki eksportu.
    • PITR_TIMESTAMP – sygnatura czasowa 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 grup kolekcji, np. 'specific-collection-group1','specific-collection-group2'.
    • NAMESPACE_IDS – lista identyfikatorów przestrzeni nazw, np. 'customer','orders'.

    Zanim wyeksportujesz dane PITR, weź pod uwagę te informacje:

    • Sygnatura czasowa w formacie RFC 3339. Na przykład 2023-05-26T10:20:00.00Z lub 2023-10-19T10:30:00.00-07:00.
    • Pamiętaj, aby podany przez Ciebie znacznik czasu odpowiadał całej minucie z ostatnich 7 dni, ale nie wcześniejszej niż earliestVersionTime. Jeśli dane nie istnieją już w określonym punkcie czasowym, generowany jest błąd. Sygnatura czasowa musi być podawana z dokładnością do minuty, nawet jeśli podany czas przypada w ciągu ostatniej godziny.
    • Nie obciążamy Cię kosztem eksportu PITR, który się nie udał.

  2. importować do bazy danych;

    Aby zaimportować wyeksportowaną bazę danych, wykonaj czynności opisane w sekcji Importowanie wszystkich dokumentów. Jeśli jakiś dokument już występuje w Twojej bazie danych, zostanie zastąpiony.