Eksportowanie i importowanie danych

Usługi zarządzanego eksportu i importu w Cloud Firestore możesz używać do: odzyskiwanie danych po przypadkowym usunięciu danych i ich eksportowanie w trybie offline, o przetwarzaniu danych. Możesz wyeksportować wszystkie dokumenty lub tylko wybrane kolekcje. Podobnie, możesz zaimportować wszystkie dane z eksportu lub tylko określone kolekcje. Dane Wyeksportowaną z jednej bazy danych Cloud Firestore można zaimportować do innej Baza danych Cloud Firestore. Możesz też wczytać Cloud Firestore eksportuje dane do BigQuery.

Na tej stronie dowiesz się, jak eksportować i importować dokumenty Cloud Firestore za pomocą usługę zarządzanego eksportu i importu oraz Cloud Storage. Zarządzana usługa eksportu i importu Cloud Firestore jest dostępna w gcloud narzędzia wiersza poleceń i Cloud Firestore API (REST, RPC).

Zanim zaczniesz

Aby móc korzystać z usługi zarządzanego eksportu i importu, musisz wykonać następujące zadania:

1. Włącz płatności za projekt Google Cloud. Tylko Google Cloud w projektach z włączonymi płatnościami można używać funkcji eksportowania i importowania.
2. Utwórz Zasobnik Cloud Storage dla Twojego projektu w lokalizacji w pobliżu Lokalizacja bazy danych Cloud Firestore Nie można użyć Żądający płaci zasobnik za operacje eksportu i importu.

3. Upewnij się, że Twoje konto ma wymagane uprawnienia Cloud Firestore i Cloud Storage. Jeśli jesteś właścicielem projektu, ma odpowiednie uprawnienia. W przeciwnym razie: role dają niezbędne uprawnienia do operacji eksportu i importu, aby uzyskać dostęp do Cloud Storage:

   • Role w Cloud Firestore: Owner, Cloud Datastore Owner lub Cloud Datastore Import Export Admin

   • Role w Cloud Storage: Owner lub Storage Admin

Uprawnienia agenta usługi

Operacje eksportu i importu wykorzystują agenta usługi Cloud Firestore do autoryzować operacje w Cloud Storage. Agent usługi Cloud Firestore zgodnie z następującą konwencją nazewnictwa:

Agent usługi Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Więcej informacji o agentach usługi znajdziesz w artykule Agenty usługi.

Agent usługi Cloud Firestore wymaga dostępu do Zasobnik Cloud Storage używany w operacji eksportu lub importu. Jeśli Zasobnik Cloud Storage jest w tym samym projekcie co Cloud Firestore w bazie danych, agent usługi Cloud Firestore będzie miał dostęp do zasobnika.

Jeśli zasobnik Cloud Storage znajduje się w innym projekcie, musi przyznać agentowi usługi Cloud Firestore dostęp do Cloud Storage zasobnika.

Przypisz role do agenta usługi

Możesz użyć narzędzia wiersza poleceń gsutil, aby: przypisać mu jedną z poniższych ról. Aby na przykład przypisać rolę Administrator miejsca na dane do agenta usługi Cloud Firestore, uruchom to polecenie:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Zastąp PROJECT_NUMBER numerem projektu, który posłuży do nadania nazwy agentowi usługi Cloud Firestore. Aby wyświetlić nazwa agenta usługi – przeczytaj artykuł Wyświetlanie nazwy agenta usługi.

Ewentualnie możesz przypisać tę rolę za pomocą konsoli GCP.

Wyświetl nazwę agenta usługi

Możesz wyświetlić konto używane do autoryzacji operacji importowania i eksportowania na stronie Import/eksport w konsoli Google Cloud Platform. Możesz też sprawdź, czy Twoja baza danych korzysta z Cloud Firestore lub starszego konta usługi App Engine.

1. Wyświetl konto autoryzacji obok Etykieta Zadania importu/eksportu uruchamiane jako.

Agent usługi wymaga roli Storage Admin w Cloud Storage zasobnika, którego chcesz użyć w operacji eksportu lub importu.

Skonfiguruj usługę gcloud w projekcie

Operacje importu i eksportu możesz zainicjować w konsoli Google Cloud Platform lub narzędzia wiersza poleceń gcloud. Aby użyć narzędzia gcloud, skonfiguruj narzędzie wiersza poleceń i połącz się z nim na jeden z tych sposobów:

• Uzyskaj dostęp do usługi gcloud z poziomu konsoli Google Cloud Platform za pomocą Cloud Shell.

  Uruchamianie Cloud Shell

  Sprawdź, czy usługa gcloud jest skonfigurowana dla właściwego projektu:

  gcloud config set project [PROJECT_ID]
  

• Zainstaluj i zainicjuj pakiet SDK Google Cloud.

Eksportuj dane

Operacja eksportu powoduje skopiowanie dokumentów z bazy danych do zbioru plików w Zasobnik Cloud Storage. Pamiętaj, że eksport nie jest dokładnym wykonaniem zrzutu bazy danych w momencie rozpoczęcia eksportu. Eksport może zawierać zmiany wprowadzone w trakcie operacji było uruchomione.

Eksportuj wszystkie dokumenty

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Eksportowanie określonych kolekcji

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
--database=[DATABASE]

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Eksport z sygnatury czasowej PITR

Możesz wyeksportować bazę danych do Cloud Storage z danych PTR. za pomocą polecenia gcloud firestore export. Możesz eksportować dane PITR, gdzie sygnatura czasowa to pełna minuta w ciągu ostatnich 7 dni, ale nie wcześniej niż w miesiącu: earliestVersionTime. Jeśli dane nie są już istnieje z podaną sygnaturą czasową, operacja eksportu nie powiedzie się.

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

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,

   • PITR_TIMESTAMP – sygnatura czasowa PITR z dokładnością co do minuty, np. 2023-05-26T10:20:00.00Z.

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

   • Podaj sygnaturę czasową w dokumencie RFC 3339 . Na przykład: 2020-09-01T23:59:30.234233Z.
   • Upewnij się, że podana sygnatura czasowa to sygnatura czasowa obejmująca całą minutę w ciągu ostatnich 7 dni, ale nie wcześniej niż earliestVersionTime Jeśli w określonym miejscu nie ma już danych , pojawia się błąd.
   • Nie obciążymy Cię płatnością za nieudany eksport PITR.

Importuj dane

Po wyeksportowaniu plików w Cloud Storage możesz w nich zaimportować dokumenty pliki z powrotem do projektu lub innego projektu. Pamiętaj o tych kwestiach o operacjach importu:

• Gdy importujesz dane, wymagane indeksy są aktualizowane przy użyciu aktualne definicje indeksów. Wyeksportowane dane nie zawierają definicji indeksów.

• Importy nie powodują przypisania nowych identyfikatorów dokumentów. Import korzysta z identyfikatorów zarejestrowanych w w momencie eksportu. Gdy dokument jest importowany, jego identyfikator jest zarezerwowany aby zapobiec konfliktom identyfikatorów. Jeśli istnieje już dokument o tym samym identyfikatorze, parametr zastąpi istniejący dokument.

• Jeśli importowanie nie wpłynie na dokument w bazie danych, dokument pozostanie w bazie danych po zaimportowaniu ich.

• Operacje importu nie aktywują funkcji w Cloud Functions. Detektory zrzutów otrzymywać aktualizacje związane z operacjami importu.

• Nazwa pliku .overall_export_metadata musi być taka sama jak nazwa elementu nadrzędnego folder:

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

  Jeśli przeniesiesz lub skopiujesz pliki wyjściowe eksportu, zachowaj plik PARENT_FOLDER_NAME i .overall_export_metadata nadają plikom nazwy tak samo.

Importuj wszystkie dokumenty z eksportu

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Importuj określone kolekcje

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
  --database=[DATABASE]

Importowanie eksportu PITR

Aby zaimportować wyeksportowane pliki, wykonaj czynności opisane w artykule Importowanie wszystkich dokumentów. w bazie danych. Jeśli jakikolwiek dokument znajduje się już w bazie danych, zostanie nadpisana.

zarządzanie operacjami eksportu i importu;

Gdy rozpoczniesz operację eksportu lub importu, Cloud Firestore przypisze i nadać operacji unikalną nazwę. Możesz użyć nazwy operacji, aby usunąć anulować lub sprawdzić stan operacji.

Nazwy operacji mają prefiks projects/[PROJECT_ID]/databases/(default)/operations/, np.:

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Możesz jednak pominąć ten prefiks podczas określania nazwy operacji dla describe, cancel i delete.

Wyświetlanie listy wszystkich operacji eksportu i importu

gcloud firestore operations list

Sprawdź stan operacji

gcloud firestore operations describe [OPERATION_NAME]

Oszacuj czas realizacji

Żądanie dotyczące stanu długo trwającej operacji zwraca wskaźniki workEstimated i workCompleted. Każdy z tych wskaźników jest zwracany w obu liczba bajtów i liczba encji:

• workEstimated pokazuje szacunkową łączną liczbę bajtów i dokumentów . Cloud Firestore może pominąć ten wskaźnik, jeśli nie może dokonać szacunków.

• workCompleted pokazuje liczbę bajtów i dokumentów przetworzonych do tej pory. Po jej zakończeniu wartość to łączna liczba wartości liczba faktycznie przetworzonych bajtów i dokumentów (może być większa niż workEstimated.

Aby uzyskać przybliżone oszacowanie postępu, podziel workCompleted przez workEstimated. Ten szacunki mogą być niedokładne, ponieważ zależą od opóźnionych statystyk kolekcji.

Anulowanie operacji

gcloud firestore operations cancel [OPERATION_NAME]

Anulowanie uruchomionej operacji nie powoduje jej cofnięcia. Eksport anulowany spowoduje, że dokumenty, które zostały już wyeksportowane do Cloud Storage, zostaną anulowane, w operacji importu pozostawią aktualizacje wprowadzone już w Twojej bazie danych. Ty nie można zaimportować częściowo ukończonego eksportu.

Usuwanie operacji

Użyj polecenia gcloud firestore operations delete, aby usunąć wybierz operację z listy ostatnich operacji. To polecenie nie spowoduje usunięcia wyeksportować pliki z Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

Płatności i ceny za operacje eksportu i importu

Aby używać projektu Google Cloud, musisz włączyć płatności w usłudze zarządzanego eksportu i importu.

Opłaty za operacje eksportu i importu są naliczane dla odczytów i zapisów dokumentów z szybkościami podanymi w Cennik Cloud Firestore Operacje eksportu powodują jeden odczyt operacji na wyeksportowanym dokumencie. Operacje importu wymagają jednej operacji zapisu na Zaimportowano dokument.

Pliki wyjściowe przechowywane w Cloud Storage są wliczane do limitu Koszty przechowywania danych w Cloud Storage.

Koszty eksportu i importu nie wliczają się do wydatków . Operacje eksportu lub importu nie będą aktywować Alerty dotyczące budżetu Google Cloud będą dostępne po zakończeniu. Podobnie odczyty i zapisy wykonane podczas operacji eksportu lub importu są stosowane do limitu dziennego po zakończeniu tej operacji. Eksportowanie i importowanie nie będą miały wpływu na wykorzystanie widoczne w sekcji wykorzystania w konsoli.

Wyświetlanie kosztów eksportu i importu

Operacje eksportu i importu stosują goog-firestoremanaged:exportimport do rozliczanych operacji. Na stronie Raporty dotyczące rozliczeń usługi Google Cloud: możesz użyć tej etykiety, aby wyświetlić koszty związane z operacjami importu i eksportu:

Eksportuj do BigQuery

Możesz wczytać dane z eksportu Cloud Firestore do BigQuery, ale tylko wtedy, gdy został określony filtr collection-ids. Zobacz Wczytuję dane z eksportów Cloud Firestore.

Limit kolumn BigQuery

BigQuery nakłada limit 10 000 kolumn na tabelę. Operacje eksportu w Cloud Firestore generują tabelę BigQuery dla każdej grupy kolekcji. W tym schemacie każda unikalna nazwa pola w obrębie grupa kolekcji staje się kolumną schematu.

Jeśli schemat BigQuery grupy kolekcji przekracza 10 000 kolumn, Operacja eksportu w Cloud Firestore próbuje zmieścić się w limicie kolumn traktując pola mapy jako bajty. Jeśli ta konwersja generuje dla liczby kolumn poniżej 10 000, możesz wczytać dane BigQuery, ale nie można wysyłać zapytań dotyczących pól podrzędnych w polach mapy. Jeśli liczba kolumn nadal przekracza 10 000, operacja eksportu nie wygeneruj schemat BigQuery dla grupy kolekcji i nie możesz wczytać swoje dane do BigQuery.

Eksportuj pliki w formacie i metadanych

W danych wyjściowych eksportu zarządzanego używane są: Format logu LevelDB.

Pliki metadanych

Operacja eksportu tworzy plik metadanych dla każdej grupy kolekcji określonych przez Ciebie. Pliki metadanych mają zwykle nazwy ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata

Pliki metadanych są buforami protokołów i możesz je dekodować za pomocą Kompilator protokołu protoc. Możesz na przykład zdekodować plik metadanych, aby określić grupy kolekcji. pliki eksportu zawierają:

protoc --decode_raw < export0.export_metadata

Migracja agenta usługi

Cloud Firestore używa agenta usługi Cloud Firestore do autoryzowania importu i eksportować operacje, zamiast korzystać z konta usługi App Engine. Agent usługi i konto usługi używają tych konwencji nazewnictwa:

Agent usługi Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Dotychczas Cloud Firestore używał domyślnej usługi App Engine a nie agenta usługi Cloud Firestore. Jeśli Twoja baza danych nadal używa konta usługi App Engine do importowania lub eksportowania danych, zalecamy wykonanie instrukcji opisanych w tej sekcji w celu przeprowadzenia migracji do agenta usługi Cloud Firestore.

Konto usługi App Engine

PROJECT_ID@appspot.gserviceaccount.com

Agent usługi Cloud Firestore jest zalecany, ponieważ jest specyficzny do Cloud Firestore. Konto usługi App Engine jest współdzielone w więcej niż 1 usłudze.

Wyświetl konto autoryzacji

Możesz sprawdzić, którego konta używają do autoryzacji operacje importowania i eksportowania na stronie Import/eksport w konsoli Google Cloud Platform. Możesz też sprawdź, czy Twoja baza danych korzysta już z Cloud Firestore .

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 Import/Export (Importuj/eksportuj).

4. Wyświetl konto autoryzacji obok Etykieta Zadania importu/eksportu uruchamiane jako.

Jeśli Twój projekt nie korzysta z agenta usługi Cloud Firestore, można przeprowadzić migrację do agenta usługi Cloud Firestore przy użyciu jednej z tych metod:

• Przeprowadź migrację projektu przez sprawdzenie i zaktualizowanie uprawnień zasobnika Cloud Storage (zalecane).
• Dodaj ograniczenie zasad dla całej organizacji, które ma wpływ na wszystkie projekty w obrębie organizacji. Twojej organizacji.

Pierwsza z nich jest lepsza, ponieważ pozwala lokalizować zakres na pojedynczy projekt Cloud Firestore. Druga metoda nie preferowane, ponieważ nie przenosi istniejącego zasobnika Cloud Storage uprawnień. Zapewnia jednak zgodność z zasadami zabezpieczeń w organizacji na poziomie 300%.

Przeprowadź migrację przez sprawdzenie i zaktualizowanie uprawnień zasobnika Cloud Storage

Proces migracji składa się z 2 etapów:

1. Zaktualizuj uprawnienia zasobnika Cloud Storage. W następnej sekcji znajdziesz informacje na temat .
2. Potwierdź migrację do agenta usługi Cloud Firestore.

Uprawnienia do zasobnika agenta usługi

Operacje eksportu lub importu korzystające z zasobnika Cloud Storage innego projektu, musisz przypisać agenta usługi Cloud Firestore dla tego zasobnika. Na przykład operacje przenoszenia danych do innej musi mieć dostęp do zasobnika w tym projekcie. W przeciwnym razie operacje po migracji do usługi Cloud Firestore kończą się niepowodzeniem .

Przepływy pracy importowania i eksportowania, które pozostają w tym samym projekcie, nie wymagają zmiany uprawnień. Agent usługi Cloud Firestore ma dostęp które domyślnie znajdują się w tym samym projekcie.

Zaktualizuj uprawnienia zasobników Cloud Storage z innych projektów, aby przyznać dostęp do service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com . Przypisz agentowi usługi rolę Firestore Service Agent.

Rola Firestore Service Agent przyznaje uprawnienia do odczytu i zapisu dla Zasobnik Cloud Storage. Jeśli musisz przyznać uprawnienia tylko do odczytu lub tylko do zapisu uprawnień, użyj rolę niestandardową.

Proces migracji opisany w następnej sekcji pomaga zidentyfikować Cloud Storage które mogą wymagać aktualizacji uprawnień.

Migracja projektu do agenta usługi Firestore

Aby przeprowadzić migrację z konta usługi App Engine do agenta usługi Cloud Firestore. Po zakończeniu migracji nie będzie można cofnięto.

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 Import/Export (Importuj/eksportuj).

4. Jeśli Twój projekt nie został jeszcze przeniesiony do usługi Cloud Firestore zobaczysz baner z opisem migracji i przycisk Sprawdź stan zasobnika. Następny krok pomoże Ci określić naprawiania potencjalnych błędów związanych z uprawnieniami.

   Kliknij Sprawdź stan zasobnika.

   Pojawi się menu z opcją zakończenia migracji i listę zasobników Cloud Storage. Może minąć kilka minut, zanim listę, by dokończyć wczytywanie.

   Ta lista zawiera zasobniki, które zostały ostatnio używane w operacjach importu i eksportu, ale obecnie nie udostępniają uprawnienia do zapisu w agencie usługi Cloud Firestore.

5. Zanotuj nazwę podmiotu zabezpieczeń Cloud Firestore w Twoim projekcie . Nazwa agenta usługi jest widoczna w sekcji Etykieta Agent usługi, do której można przyznać dostęp.

6. Dla każdego zasobnika na liście, który zostanie użyj do przyszłych operacji importu lub eksportu, wykonaj te czynności kroki:

   1. W wierszu tabeli tego zasobnika kliknij Napraw. Spowoduje to otwarcie strony uprawnień zasobnika w nowej karcie.

   2. Kliknij Dodaj.
   3. W polu Nowe podmioty zabezpieczeń wpisz nazwę Agent usługi Cloud Firestore.
   4. W polu Wybierz rolę kliknij Agenty usługi > Agent usługi Firestore.
   5. Kliknij Zapisz.
   6. Wróć na kartę ze stroną importowania/eksportowania w Cloud Firestore.
   7. Powtórz te kroki dla innych zasobników na liście. Pamiętaj, aby wyświetlić wszystkich stronach listy.

7. Kliknij Migracja do agenta usługi Firestore. Jeśli nadal mają zasobniki z nieudaną weryfikacją uprawnień, musisz potwierdzić migrację, klikając Migrate (Przenieś).

   Alert informuje o zakończeniu migracji. Migracja nie jest możliwa cofnięto.

Wyświetl stan migracji

Aby sprawdzić stan migracji projektu:

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 Import/Export (Importuj/eksportuj).

4. Znajdź podmiot zabezpieczeń obok etykiety Zadania importu/eksportu uruchomione jako.

   Jeśli podmiotem zabezpieczeń jest service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, oznacza to, że Twój projekt został już przeniesiony do Cloud Firestore . Migracji nie można cofnąć.

   Jeśli projekt nie został przeniesiony, u góry strony pojawi się baner klikając przycisk Sprawdź stan zasobnika. Zobacz Migracja do agenta usługi Firestore aby dokończyć migrację.

Dodaj ograniczenie wynikające z zasad obowiązujących w całej organizacji

• Ustaw to ograniczenie w zasadzie organizacji:

  Wymagaj agenta usługi Firestore przy importowaniu i eksportowaniu (firestore.requireP4SAforImportExport).

  To ograniczenie wymaga operacji importu i eksportu do użycia Agent usługi Cloud Firestore do autoryzowania żądań. Aby ustawić to ograniczenie, zobacz Tworzenie zasad organizacji i zarządzanie nimi .

Zastosowanie tego ograniczenia zasady organizacji nie powoduje automatycznego przyznania odpowiednie uprawnienia do zasobnika Cloud Storage Agent usługi Cloud Firestore.

Jeśli ograniczenie powoduje błędy uprawnień w przepływach pracy importowania lub eksportowania, możesz ją wyłączyć, by powrócić do domyślnego konta usługi. Po sprawdzeniu i zaktualizowaniu zasobnika Cloud Storage uprawnienia, możesz je ponownie włączyć.