Eksportowanie i importowanie danych

Możesz korzystać z usługi zarządzanego eksportu i importu Cloud Firestore, aby przywracać przypadkowo usunięte dane lub eksportować dane do przetwarzania w trybie offline. Możesz wyeksportować wszystkie dokumenty lub tylko określone kolekcje. Podobnie możesz importować wszystkie dane z pliku eksportu lub tylko określone kolekcje. Dane wyeksportowane z jednej bazy danych Cloud Firestore można zaimportować do innej bazy danych Cloud Firestore. Możesz też wczytaćCloud Firestore eksporty do BigQuery.

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

Zanim zaczniesz

Zanim zaczniesz korzystać z usługi zarządzanego eksportu i importu, musisz wykonać te czynności:

1. Włącz płatności w projekcie Google Cloud. Funkcji eksportowania i importowania mogą używać tylko projekty Google Cloud z włączonymi płatnościami.
2. Utwórz zasobnik Cloud Storage dla projektu w miejscu zbliżonym do lokalizacji bazy danych Cloud Firestore. Nie możesz używać puli taryfy prośby o eksport i import.

3. Sprawdź, czy Twoje konto ma wymagane uprawnienia Cloud Firestore i Cloud Storage. Jeśli jesteś właścicielem projektu, Twoje konto ma wymagane uprawnienia. W przeciwnym razie te role przyznają niezbędne uprawnienia do operacji eksportu i importu oraz dostęp do Cloud Storage:

   • Rola Cloud Firestore: Owner, Cloud Datastore Owner lub Cloud Datastore Import Export Admin

   • Rola Cloud Storage: Owner lub Storage Admin

Uprawnienia agenta usługi

Operacje eksportowania i importowania korzystają z agenta usługi Cloud Firestore do autoryzowania operacji Cloud Storage. Agent usługi Cloud Firestore używa tej konwencji nazewnictwa:

Cloud Firestore agent usługi

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 zasobnika Cloud Storage używanego w operacji eksportu lub importu. Jeśli zasobnik Cloud Storage znajduje się w tym samym projekcie co baza danych Cloud Firestore, agent usługi Cloud Firestore może domyślnie uzyskać do niego dostęp.

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

Przypisywanie ról agentowi usługi

Za pomocą narzędzia wiersza poleceń gsutil możesz przypisać użytkownikowi jedną z ról wymienionych poniżej. Aby na przykład przypisać rolę administratora miejsca na dane do konta 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 służy do nazwania Cloud Firestore agenta usługi. Aby wyświetlić nazwę agenta usługi, zapoznaj się z artykułem Wyświetlanie nazwy agenta usługi.

Możesz też przypisać tę rolę za pomocą konsoli Google Cloud.

Wyświetlanie nazwy agenta usługi

Na stronie Import/eksport w konsoli Google Cloud możesz sprawdzić konto, którego używają operacje importowania i eksportowania do autoryzacji żądań. Możesz też sprawdzić, czy Twoja baza danych korzysta z usługi Cloud Firestore agenta usługi czy starszego konta usługi App Engine.

1. Obok etykiety Zadania importu/eksportu są uruchamiane jako wyświetl konto autoryzacyjne.

Agent usługi musi mieć rolę Storage Admin w przypadku zasobnika Cloud Storage, który ma być używany do operacji eksportowania lub importowania.

Konfigurowanie gcloud w projekcie

Operacje importowania i eksportowania możesz inicjować w konsoli Google Cloud lub za pomocą narzędzia wiersza poleceń gcloud. Aby korzystać z gcloud, skonfiguruj narzędzie wiersza poleceń i połącz się z projektem w jeden z tych sposobów:

• Otwórz gcloud w konsoli Google Cloud Platform, używając Cloud Shell.

  Rozpocznij Cloud Shell

  Upewnij się, że gcloud jest skonfigurowany na potrzeby odpowiedniego projektu:

  gcloud config set project [PROJECT_ID]
  

• Zainstaluj i zainicjuj pakiet Google Cloud SDK.

Eksportuj dane

Operacja eksportu kopiuje dokumenty z bazy danych do zbioru plików w zasobniku Cloud Storage. Pamiętaj, że eksport nie jest dokładnym miganym bazy danych wykonanym w momencie rozpoczęcia eksportu. Eksport może zawierać zmiany wprowadzone podczas wykonywania operacji.

Eksportowanie wszystkich dokumentów

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

Eksportowanie konkretnych 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'

Eksportowanie z sygnatury czasowej PITR

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

Operacja eksportu PITR obsługuje wszystkie filtry, w tym eksport wszystkich dokumentów i wybranych 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

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

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

   • Sygnatura czasowa w formacie RFC 3339. Na przykład: 2020-09-01T23:59:30.234233Z.
   • 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.
   • Nie obciążamy Cię kosztem eksportu PITR, który się nie udał.

Importuj dane

Po wyeksportowaniu plików w Cloud Storage możesz zaimportować dokumenty z tych plików z powrotem do projektu lub do innego projektu. Pamiętaj o tych kwestiach dotyczących operacji importowania:

• Podczas importowania danych wymagane indeksy są aktualizowane za pomocą bieżących definicji indeksów bazy danych. Eksport nie zawiera definicji indeksów.

• Podczas importowania nie przypisuje się nowych identyfikatorów dokumentów. Importy używają identyfikatorów zarejestrowanych w momencie eksportu. Podczas importowania dokumentu jego identyfikator jest zarezerwowany, aby zapobiec kolizji identyfikatorów. Jeśli dokument o tym samym identyfikatorze już istnieje, importowanie go spowoduje zastąpienie istniejącego dokumentu.

• Jeśli import nie ma wpływu na dokument w Twojej bazie danych, pozostanie on w bazie po zaimportowaniu.

• Operacje importu nie aktywują funkcji w Cloud Functions. Detektory zrzutów otrzymują informacje o operacjach importowania.

• Nazwa pliku .overall_export_metadata musi być zgodna z nazwą folderu nadrzędnego:

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

  Jeśli przenosisz lub kopiujesz pliki wyjściowe eksportu, zachowaj nazwy plików PARENT_FOLDER_NAME i .overall_export_metadata.

Importowanie wszystkich dokumentów z pliku wyeksportowanego

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

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

Importowanie konkretnych kolekcji

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

Importowanie pliku eksportu PITR

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.

Zarządzanie operacjami eksportu i importu

Po rozpoczęciu operacji eksportu lub importu Cloud Firestore przypisuje do niej unikalną nazwę. Nazwa operacji umożliwia jej usunięcie, anulowanie lub sprawdzenie stanu.

Nazwa działania ma prefiks projects/[PROJECT_ID]/databases/(default)/operations/, na przykład:

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

Możesz jednak pominąć prefiks, podając nazwę operacji w przypadku poleceń describe, cancel i delete.

Wyświetlanie listy wszystkich operacji eksportu i importu

gcloud firestore operations list

Sprawdzanie stanu operacji

gcloud firestore operations describe [OPERATION_NAME]

Szacowanie czasu ukończenia

Żądanie dotyczące stanu długo trwającej operacji zwraca dane workEstimated i workCompleted. Każdy z tych rodzajów danych jest zwracany w postaci liczby bajtów i liczby elementów:

• workEstimated zawiera szacowaną łączną liczbę bajtów i dokumentów, które zostaną przetworzone przez operację. Cloud Firestore może pominąć te dane, jeśli nie może podać ich szacunkowej wartości.

• workCompleted pokazuje liczbę przetworzonych do tej pory bajtów i dokumentów. Po zakończeniu operacji wartość pokazuje łączną liczbę bajtów i rzeczywistą liczbę przetworzonych dokumentów, która może być większa niż wartość parametru workEstimated.

Aby uzyskać przybliżony szacowany postęp, podziel workCompleted przez workEstimated. Ta szacowana wartość może być niedokładna, ponieważ zależy od opóźnionego zbierania statystyk.

Anulowanie operacji

gcloud firestore operations cancel [OPERATION_NAME]

Anulowanie trwającej operacji nie powoduje jej cofnięcia. Anulowanie operacji eksportu spowoduje pozostawienie dokumentów już wyeksportowanych w Cloud Storage, a anulowanie operacji importu spowoduje pozostawienie zmian wprowadzonych już w bazie danych. Nie możesz zaimportować częściowo zakończonego eksportu.

Usuwanie operacji

Aby usunąć operację z listy ostatnich operacji, użyj polecenia gcloud firestore operations delete. To polecenie nie spowoduje usunięcia plików z Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

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

Zanim zaczniesz korzystać z usługi zarządzanego eksportu i importu, musisz włączyć płatności w projekcie Google Cloud.

Operacje eksportu i importu są naliczane za odczyt i zapis dokumentu według stawek podanych w Cloud FirestoreCeny. Operacje eksportu powodują jedną operację odczytu na każdy eksportowany dokument. Operacje importowania powodują jedną operację zapisu na każdy zaimportowany dokument.

Pliki wyjściowe zapisane w Cloud Storage są wliczane do kosztów przechowywania danych w Cloud Storage.

Koszty operacji eksportu i importu nie wliczają się do limitu wydatków. Operacje eksportowania i importowania nie będą powodować wysyłania alertów dotyczących Google Cloudbudżetu, dopóki nie zostaną ukończone. Podobnie odczyty i zapisy wykonane podczas operacji eksportu lub importu są stosowane do tego dnia, w którym operacja została zakończona. Operacje eksportowania i importowania nie mają wpływu na dane o użytkowaniu wyświetlane w sekcji Użycie w konsoli.

Wyświetlanie kosztów eksportu i importu

Operacje eksportu i importu stosują etykietę goog-firestoremanaged:exportimport do operacji naliczania opłat. Na stronie raportów 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

Dane z poziomu Cloud Firestore możesz załadować do poziomu BigQuery, ale tylko wtedy, gdy określisz filtr collection-ids. Zobacz Ładowanie danych z eksportu Cloud Firestore.

BigQuery limit kolumn

BigQuery narzuca limit 10 tys. kolumn na tabelę. Operacje eksportu Cloud Firestore generują BigQueryschemat tabeli dla każdej grupy kolekcji. W tym schemacie każda unikalna nazwa pola w grupie kolekcji staje się kolumną schematu.

Jeśli schemat BigQuery grupy kolekcji przekracza 10 tys. kolumn,operacja eksportu Cloud Firestore próbuje pozostać poniżej limitu kolumn, traktując pola mapy jako bajty. Jeśli po takiej konwersji liczba kolumn spadnie poniżej 10 tys., możesz załadować dane do tabeli BigQuery, ale nie możesz wysyłać zapytań do podpól w polach mapy. Jeśli liczba kolumn nadal przekracza 10 tys. kolumn,operacja eksportu nie wygeneruje schematu BigQuery dla grupy kolekcji, a jej dane nie zostaną załadowane do BigQuery.

Eksportowanie plików z formatem i metadanymi

Dane wyjściowe eksportu zarządzanego są zapisywane w formacie logów LevelDB.

Pliki metadanych

Operacja eksportu tworzy plik metadanych dla każdej określonej przez Ciebie grupy zbiorów. Pliki metadanych mają zwykle nazwę ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

Pliki metadanych to bufory protokołu, które możesz zdekodować za pomocą kompilatora protokołu protoc. Możesz na przykład odkodować plik metadanych, aby określić grupy kolekcji, które zawierają pliki eksportu:

protoc --decode_raw < export0.export_metadata

Migracja agenta usługi

Cloud Firestore używa agenta usługi Cloud Firestore do autoryzowania operacji importowania i eksportowania zamiast używać konta usługi App Engine. Usługa agenta i konto usługi używają tych konwencji nazewnictwa:

Cloud Firestore agent usługi

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

Usługa Cloud Firestore korzystała wcześniej z domyślnego konta usługi App Engine zamiast z konta 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 podanych w tym rozdziale, aby przejść na korzystanie z agenta usługi Cloud Firestore.

App Engine konto usługi

PROJECT_ID@appspot.gserviceaccount.com

Użycie agenta usługi Cloud Firestore jest preferowane, ponieważ jest ono związane z Cloud Firestore. Konto usługi App Engine jest współużytkowane przez więcej niż 1 usługę.

Wyświetlanie konta autoryzacji

Na stronie Import/eksport w konsoli Google Cloud możesz sprawdzić, którego konta używają operacje importowania i eksportowania do autoryzowania żądań. Możesz też sprawdzić, czy Twoja baza danych korzysta już z usługi Cloud Firestore.

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

   Otwórz stronę Bazy danych

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

3. W menu nawigacyjnym kliknij Importuj/Eksportuj.

4. Obok etykiety Zadania importu/eksportu są uruchamiane jako wyświetl konto autoryzacyjne.

Jeśli Twój projekt nie korzysta z agenta usługi Cloud Firestore, możesz przejść na agenta usługi Cloud Firestore, korzystając z jednej z tych technik:

• Migracja projektu przez sprawdzenie i zaktualizowanie uprawnień zasobnika Cloud Storage (zalecane).
• Dodaj ograniczenie zasad na poziomie organizacji, które będzie dotyczyć wszystkich projektów w organizacji.

Pierwsza z tych technik jest preferowana, ponieważ ogranicza zasięg efektu do jednego projektu Cloud Firestore. Druga metoda nie jest zalecana, ponieważ nie migruje istniejących uprawnień zbioru Cloud Storage. Zapewnia jednak zgodność z zasadami bezpieczeństwa na poziomie organizacji.

Migracja polegająca na sprawdzeniu i zaktualizowaniu uprawnień zasobnika Cloud Storage

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

1. Zaktualizuj uprawnienia zasobnika Cloud Storage. Więcej informacji znajdziesz w sekcji poniżej.
2. Potwierdź migrację agentowi obsługi klienta Cloud Firestore.

Uprawnienia zasobnika agenta usługi

W przypadku operacji eksportu lub importu, które korzystają z zasobnika Cloud Storage w innym projekcie, musisz przyznać uprawnienia Cloud Firestore dla tego zasobnika. Na przykład operacje przenoszenia danych do innego projektu muszą mieć dostęp do zasobnika w tym projekcie. W przeciwnym razie te operacje nie powiedzą się po migracji do usługi Cloud Firestore.

Zadania importowania i eksportowania, które pozostają w tym samym projekcie, nie wymagają zmiany uprawnień. Domyślnie agent usługi Cloud Firestore ma dostęp do zasobów w tym samym projekcie.

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

Rola Firestore Service Agent przyznaje uprawnienia do odczytu i zapisu w zasośniku Cloud Storage. Jeśli chcesz przyznać tylko uprawnienia do odczytu lub tylko uprawnienia do zapisu, użyj niestandardowej roli.

Proces migracji opisany w sekcji poniżej pomoże Ci zidentyfikować zbiory Cloud Storage, które mogą wymagać aktualizacji uprawnień.

Migracja projektu do agenta usługi Firestore

Aby przejść z konta usługi App Engine na agenta usługi Cloud Firestore, wykonaj te czynności. Po zakończeniu migracji nie można jej cofnąć.

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

   Otwórz stronę Bazy danych

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

3. W menu nawigacyjnym kliknij Importuj/Eksportuj.

4. Jeśli Twój projekt nie został jeszcze przeniesiony do usługi Cloud Firestore, zobaczysz baner opisujący migrację oraz przycisk Sprawdź stan zasobnika. Następny krok pomoże Ci zidentyfikować i poprawić potencjalne błędy dotyczące uprawnień.

   Kliknij Sprawdź stan zasobnika.

   Pojawi się menu z opcją ukończenia migracji i listą Cloud Storage. Załadowanie listy może potrwać kilka minut.

   Lista zawiera zasobniki, które były niedawno używane w operacjach importu i eksportu, ale obecnie nie przyznają uprawnień do odczytu i zapisu agentowi usługi Cloud Firestore.

5. Zanotuj nazwę podmiotu zabezpieczeń agenta usługi Cloud Firestore Twojego projektu. Nazwa agenta usługi pojawi się pod etykietą Agent usługi, któremu chcesz przyznać dostęp.

6. W przypadku zasobnika z listy, którego będziesz używać do przyszłych operacji importowania lub eksportowania, wykonaj te czynności:

   1. W wierszu tabeli tego zasobu kliknij Napraw. Spowoduje to otwarcie w nowej karcie strony z uprawnieniami danego zasobnika.

   2. Kliknij Dodaj.
   3. W polu Nowe podmioty zabezpieczeń wpisz nazwę swojego agenta ds. obsługi klienta Cloud Firestore.
   4. W polu Wybierz rolę kliknij Usługa agenta > Usługa agenta Firestore.
   5. Kliknij Zapisz.
   6. Wróć do karty z poziomem Cloud Firestore Import/Eksport.
   7. Powtórz te czynności w przypadku innych zasobników na liście. Sprawdź wszystkie strony listy.

7. Kliknij Przenieś do agenta usługi Firestore. Jeśli nadal masz zbiory z nieudanymi kontrolami uprawnień, musisz potwierdzić migrację, klikając Przeprowadź migrację.

   Powiadomienie o zakończeniu migracji. Migracji nie można cofnąć.

Wyświetlanie stanu migracji

Aby sprawdzić stan migracji projektu:

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

   Otwórz stronę Bazy danych

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

3. W menu nawigacyjnym kliknij Importuj/Eksportuj.

4. Znajdź osobę upoważnioną obok etykiety Zadania importu/eksportu są uruchamiane jako.

   Jeśli podmiot zabezpieczeń to service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, 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 z przyciskiem Sprawdź stan zasobnika. Aby dokończyć migrację, przeczytaj artykuł Migracja do agenta usługi Firestore.

Dodawanie ograniczenia dotyczącego zasad obowiązujących w całej organizacji

• W zasadach organizacji ustaw te ograniczenia:

  Wymagaj agenta usługi Firestore do importowania/eksportowania (firestore.requireP4SAforImportExport).

  To ograniczenie wymaga, aby operacje importowania i eksportowania używały agenta usługi Cloud Firestore do autoryzacji żądań. Aby ustawić to ograniczenie, zapoznaj się z artykułem Tworzenie zasad organizacji i zarządzanie nimi .

Zastosowanie tego ograniczenia zasad organizacji nie powoduje automatycznego przyznania odpowiednich uprawnień Cloud Storage dla agenta usługi Cloud Firestore.

Jeśli ograniczenie powoduje błędy uprawnień w przypadku dowolnych przepływów pracy importu lub eksportu, możesz je wyłączyć, aby wrócić do używania domyślnego konta usługi. Po sprawdzeniu i zaktualizowaniu uprawnień zasobnika Cloud Storage możesz ponownie włączyć ograniczenie.