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 zaimportować wszystkie dane z pliku eksportu lub tylko określone kolekcje. Dane wyeksportowane z jednej Cloud Firestorebazy danych można zaimportować do innejCloud Firestore. Możesz też wczytaćCloud Firestore eksporty do BigQuery.

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

Zanim zaczniesz

Aby móc 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 swojego projektu w lokalizacji w pobliżu lokalizacji bazy danych Cloud Firestore. Nie możesz używać puli taryfy prośby o płatność do operacji eksportu i importu.

3. Sprawdź, czy Twoje konto ma niezbędne 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 usługi Cloud Storage:

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

   • Role (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 ma domyślnie dostęp do zasobnika.

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ć jedną z ról wymienionych poniżej. Aby na przykład przypisać rolę administratora 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 służy do nazwania agenta usługi Cloud Firestore. Aby wyświetlić nazwę agenta usługi, przeczytaj artykuł 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 agenta usługi Cloud Firestore 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

  Sprawdź, czy usługa gcloud jest skonfigurowana dla odpowiedniego projektu:

  gcloud config set project [PROJECT_ID]
  

• Zainstaluj i zainicjuj pakiet Google Cloud SDK.

Eksportuj dane

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

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 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 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 kolekcje.

1. Wyeksportuj bazę danych, podając parametr snapshot-time jako pożądaną sygnaturę czasową przywracania.

   gcloud

   Uruchom to polecenie, aby wyeksportować bazę danych do swojego zasobnika.

   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.

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

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

Importuj dane

Po wyeksportowaniu plików w usłudze Cloud Storage możesz zaimportować zawarte w nich dokumenty z powrotem do swojego projektu lub innego projektu. Pamiętaj o tych uwagach na temat operacji importu:

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

• Importy nie powodują przypisania 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ą aktualizacje związane z operacjami 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

  W przypadku przenoszenia lub kopiowania plików wyjściowych eksportu zachowaj taką samą nazwę pliku PARENT_FOLDER_NAME i .overall_export_metadata.

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'

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

Wykonaj czynności opisane w artykule Importowanie wszystkich dokumentów, aby zaimportować eksportowaną bazę danych. 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 nadaje operacji unikalną nazwę. Za pomocą nazwy operacji możesz ją usunąć, anulować lub sprawdzić jej stan.

Nazwy działań mają prefiks projects/[PROJECT_ID]/databases/(default)/operations/, na przykład:

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

Możesz jednak pominąć ten prefiks podczas określania nazwy operacji dla 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]

Oszacuj czas realizacji

Żądanie dotyczące stanu długo trwającej operacji zwraca dane workEstimated i workCompleted. Każdy z tych rodzajów danych jest zwracany zarówno w liczbie bajtów, jak i liczbie 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ę bajtów i dokumentów przetworzonych do tej pory. Po jej zakończeniu wartość to łączna liczba bajtów i dokumentów, które zostały rzeczywiście przetworzone. Może być ona większa od wartości workEstimated.

Aby uzyskać przybliżone oszacowanie postępu, podziel workCompleted przez workEstimated. Wartość ta 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. Anulowana operacja eksportu pozostawi dokumenty już wyeksportowane w Cloud Storage, a anulowana operacja importu nie spowoduje zmian wprowadzonych 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. Nie spowoduje to usunięcia plików eksportu z: Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

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

Zanim użyjesz 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 Firestore cen. Operacje eksportu wymagają 1 operacji odczytu na wyeksportowany dokument. Operacje importu wymagają wykonania 1 operacji 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 eksportu lub importu nie będą aktywować alertów dotyczących budżetu Google Cloud, 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 eksportu i importu nie będą miały wpływu na wykorzystanie wyświetlane w sekcji wykorzystania 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 eksportu Cloud Firestore możesz wczytywać do narzędzia BigQuery, ale tylko wtedy, gdy określisz filtr collection-ids. Zobacz Wczytywanie danych z Cloud Firestore eksportów.

Limit kolumn: BigQuery

Funkcja BigQuery nakłada limit 10 tys. kolumn na tabelę. Operacje eksportu Cloud Firestore generują schemat tabeli BigQuery 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 w wyniku tej konwersji liczba kolumn spadnie poniżej 10 000, możesz wczytać dane do pola BigQuery, ale nie będzie można wysyłać zapytań dotyczących pól podrzędnych w polach mapy. Jeśli liczba kolumn nadal przekracza 10 tys., operacja eksportu nie wygeneruje schematu BigQuery dla grupy kolekcji i nie będzie można załadować jej danych do BigQuery.

Eksportuj pliki w formacie i metadanych

Dane wyjściowe eksportu zarządzanego mają format logu 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 są buforami protokołów i możesz je dekodować za pomocą kompilatora protokołów protoc. Możesz na przykład zdekodować 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. Agent usługi i konto usługi używają tych konwencji nazewnictwa:

Cloud Firestore agent usługi

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

Domena Cloud Firestore używała wcześniej domyślnego konta usługi App Engine zamiast agenta usługi Cloud Firestore. Jeśli 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ółdzielone przez więcej niż 1 usługę.

Wyświetl konto autoryzacji

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

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

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

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

• Aby przenieść projekt, sprawdź i zaktualizuj uprawnienia zasobnika Cloud Storage (zalecane).
• Dodaj ograniczenie zasad na poziomie organizacji, które będzie dotyczyć wszystkich projektów w organizacji.

Lepiej sprawdza się pierwsza z tych technik, ponieważ pozwala lokalizować zakres skutków do pojedynczego 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 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 przeniesieniu do usługi Cloud Firestore.

Przepływy pracy 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 zasobniku Cloud Storage. Jeśli chcesz przyznać uprawnienia tylko do odczytu lub tylko do zapisu, użyj roli niestandardowej.

Proces migracji opisany w sekcji poniżej pomaga zidentyfikować zasobniki 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, wykonaj opisane poniżej czynności. Po zakończeniu migracji nie można jej cofnąć.

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 Importuj/Eksportuj.

4. Jeśli Twój projekt nie został jeszcze przeniesiony do agenta usługi Cloud Firestore, zobaczysz baner opisujący migrację i 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ą zakończenia migracji i listą zasobników Cloud Storage. Załadowanie listy może potrwać kilka minut.

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

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 zasobnika 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ę wybierz Agenty usługi > Agent usługi Firestore.
   5. Kliknij Zapisz.
   6. Wróć na kartę ze stroną Import/eksport Cloud Firestore.
   7. Powtórz te czynności w przypadku innych zasobników na liście. Pamiętaj, aby wyświetlić wszystkie strony z 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ę.

   Alert informuje 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 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 agenta usługi 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. Informacje o tym, jak zakończyć migrację, znajdziesz w sekcji 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 przy importowaniu i eksportowaniu (firestore.requireP4SAforImportExport).

  To ograniczenie wymaga, aby operacje importowania i eksportowania używały Cloud Firestore agenta usługi do autoryzacji żądań. Aby ustawić to ograniczenie, zobacz 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 korzystania z domyślnego konta usługi. Po sprawdzeniu i zaktualizowaniu uprawnień zasobnika Cloud Storage możesz ponownie włączyć ograniczenie.