Eksportowanie i importowanie danych

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

Na tej stronie dowiesz się, jak eksportować i importować dokumenty Cloud Firestore za pomocą zarządzanej usługi eksportu i importu oraz Cloud Storage. Usługa eksportowania i importowania zarządzana przez Cloud Firestore jest dostępna za pomocą narzędzia wiersza poleceń gcloud oraz 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. Z funkcji eksportowania i importowania mogą korzystać tylko projekty Google Cloud z włączonymi płatnościami.
2. Utwórz Cloud Storage zasobnik na potrzeby projektu w lokalizacji w pobliżu lokalizacji Cloud Firestore bazy danych. W przypadku operacji eksportu i importu nie możesz używać zasobnika Rapid ani zasobnika, w którym płatność ponosi osoba wysyłająca żądanie.

3. Sprawdź, czy Twoje konto ma niezbędne uprawnienia do 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ępu do Cloud Storage:

   • Cloud Firestorerole: Owner, Cloud Datastore Owner lub Cloud Datastore Import Export Admin

   • Cloud Storage Role: Owner lub Storage Admin

Uprawnienia agenta usługi

Operacje eksportowania i importowania korzystają z Cloud Firestoreagenta usługiCloud Storage do autoryzowania operacji. Agent usługi Cloud Firestore korzysta z 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 Agenci usługi.

Cloud Firestore Agent usługi wymaga dostępu do zasobnika Cloud Storage używanego w operacji eksportowania lub importowania. Jeśli Twój 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ć agentowi usługi Cloud Firestore dostęp do zasobnika Cloud Storage.

Przypisywanie ról agentowi usługi

Za pomocą narzędzia wiersza poleceń gsutil możesz przypisać jedną z tych ról: Aby na przykład przypisać rolę administratora pamięci masowej agentowi 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 jest używany do nadawania nazwy agentowi usługi Cloud Firestore. Aby wyświetlić nazwę agenta usługi, zobacz Wyświetlanie nazwy agenta usługi.

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

Wyświetlanie nazwy agenta usługi

Konto, którego operacje importu i eksportu używają do autoryzowania żądań, możesz wyświetlić na stronie Import/eksport w konsoli Google Cloud. Możesz też sprawdzić, czy Twoja baza danych korzysta z Cloud Firestoreagenta usługiApp Engine czy starszego konta usługi.

1. Konto autoryzacji zobaczysz obok etykiety Zadania importu/eksportu są uruchamiane jako.

Agent usługi potrzebuje roli Storage Admin w przypadku Cloud Storage zasobnika, 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 używać 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, klikając Cloud Shell.

  Rozpocznij Cloud Shell

  Sprawdź, czy gcloud jest skonfigurowany w odpowiednim projekcie:

  gcloud config set project [PROJECT_ID]
  

• Zainstaluj i zainicjuj pakiet SDK Google Cloud.

Eksportuj dane

Operacja eksportowania kopiuje dokumenty z bazy danych do zestawu plików w zasobniku Cloud Storage. Pamiętaj, że eksport nie jest dokładną migawką bazy danych zrobioną w momencie rozpoczęcia eksportu. Eksport może obejmować zmiany wprowadzone podczas działania operacji.

Eksportowanie wszystkich dokumentów

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

Eksportowanie określonych grup kolekcji

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_GROUP_ID_1],[COLLECTION_GROUP_ID_2] \
--database=[DATABASE]

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

Eksportowanie z sygnatury czasowej PITR

Możesz wyeksportować bazę danych do Cloud Storage z danych PITR. Możesz eksportować dane PITR, których sygnatura czasowa jest pełną minutą w ciągu ostatnich 7 dni, ale nie wcześniej niż earliestVersionTime. Jeśli dane nie istnieją już w określonym sygnale czasowym, operacja eksportu zakończy się niepowodzeniem.

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

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

• Podaj sygnaturę czasową w formacie RFC 3339. Na przykład: 2023-05-26T10:20:00.00Z.
• Upewnij się, że podany znacznik czasu jest pełną minutą w ciągu ostatnich 7 dni, ale nie wcześniejszą niż earliestVersionTime. Jeśli dane nie istnieją już w określonej sygnaturze czasowej, zostanie wygenerowany błąd.
• Nie obciążymy Cię płatnością za nieudany eksport PITR.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Importuj dane

Gdy wyeksportujesz pliki do 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 przy użyciu bieżących definicji indeksów w bazie danych. Eksport nie zawiera definicji indeksów.

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

• Jeśli dokument w bazie danych nie zostanie zmieniony przez import, pozostanie w niej po zakończeniu importu.

• Operacje importowania nie aktywują funkcji Cloud Functions. Detektory zrzutu otrzymują aktualizacje związane z operacjami importowania.

• Nie dodawaj nowych Cloud Firestore dokumentów, których nie było w oryginalnych plikach wyjściowych eksportu, ani nie usuwaj żadnych istniejących dokumentów z plików GCS przed importowaniem. W przeciwnym razie import się nie powiedzie.

• .overall_export_metadata Nazwa pliku 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 tę samą nazwę pliku PARENT_FOLDER_NAME i .overall_export_metadata.

Importowanie wszystkich dokumentów 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 grup kolekcji

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_GROUP_ID_1],[COLLECTION_GROUP_ID_2] \
  --database=[DATABASE]

Importowanie wyeksportowanych danych PITR

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

Zarządzanie operacjami eksportu i importu

Po rozpoczęciu operacji eksportu lub importu Cloud Firestore przypisuje jej unikalną nazwę. Nazwy operacji możesz używać do usuwania, anulowania i sprawdzania stanu operacji.

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

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

Możesz jednak pominąć prefiks, gdy określasz nazwę operacji dla poleceń describe, cancel i delete.

Wyświetlanie wszystkich operacji eksportu i importu

gcloud firestore operations list

Sprawdzanie stanu operacji

gcloud firestore operations describe [OPERATION_NAME]

Szacowanie czasu ukończenia

Żądanie stanu długo trwającej operacji zwraca dane workEstimated i workCompleted. Każde z tych danych jest zwracane w postaci liczby bajtów i liczby jednostek:

• workEstimated – szacowana łączna liczba bajtów i dokumentów, które zostaną przetworzone w ramach operacji. Cloud Firestore może pominąć ten wskaźnik, jeśli nie może dokonać oszacowania.

• workCompleted wyświetla liczbę bajtów i dokumentów przetworzonych do tej pory. Po zakończeniu operacji wartość pokazuje łączną liczbę bajtów i dokumentów, które zostały faktycznie przetworzone. Może być ona większa niż wartość workEstimated.

Aby uzyskać przybliżone oszacowanie postępu, podziel workCompleted przez workEstimated. Ten szacunek może być niedokładny, 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 pozostawi wyeksportowane dokumenty w Cloud Storage, a anulowanie operacji importu pozostawi w bazie danych wprowadzone już zmiany. Nie możesz zaimportować częściowo ukończonego eksportu.

Usuwanie operacji

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

gcloud firestore operations delete [OPERATION_NAME]

Rozliczenia i ceny za operacje eksportu i importu

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

Operacje eksportowania i importowania są rozliczane za odczyty i zapisy dokumentów według stawek podanych w Cloud Firestorecenniku. Operacje eksportu generują jedną operację odczytu na wyeksportowany dokument. Operacje importu powodują wykonanie jednej operacji zapisu na każdy importowany dokument.

Pliki wyjściowe przechowywane w Cloud Storage są wliczane do Cloud Storagekosztów miejsca na dane.

Operacje eksportowania i importowania nie będą wywoływać alertów dotyczących Google Cloudbudżetu do czasu ich zakończenia. Operacje eksportowania i importowania 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, za które naliczane są opłaty. 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 wczytać do BigQuery, ale tylko wtedy, gdy określisz filtr collection-ids. Zobacz Wczytywanie danych z eksportów Cloud Firestore.

BigQuery limit kolumn

BigQuery ogranicza liczbę kolumn w tabeli do 10 000. Operacje eksportu Cloud Firestore generują BigQuery schemat tabeli dla każdej grupy kolekcji. W tym schemacie każda unikalna nazwa pola w grupie kolekcji staje się kolumną schematu. Jeśli schemat grupy kolekcji BigQuery przekracza 10 tys. kolumn,operacja eksportu Cloud Firestore próbuje utrzymać się w limicie kolumn, traktując pola mapy jako bajty. Jeśli po tej konwersji liczba kolumn spadnie poniżej 10 000, możesz wczytać dane do BigQuery, ale nie możesz 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 zbiorów i nie będzie można załadować jej danych do BigQuery.

Eksportowanie formatu i plików metadanych

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

Pliki metadanych

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

Pliki metadanych to bufory protokołów, które możesz dekodować za pomocą protockompilatora protokołów. Możesz na przykład zdekodować plik metadanych, aby określić grupy zbiorów, 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 importu i eksportu zamiast 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

Cloud Firestore wcześniej używał App Enginedomyślnego konta usługiCloud Firestore zamiast agenta usługi. Jeśli Twoja baza danych nadal używa konta usługi App Engine do importowania lub eksportowania danych, zalecamy wykonanie instrukcji w tej sekcji, aby przejść na korzystanie z agenta usługi Cloud Firestore.

App Engine konto usługi

PROJECT_ID@appspot.gserviceaccount.com

Cloud Firestore jest preferowanym agentem usługi, ponieważ jest on przeznaczony specjalnie dla Cloud Firestore. Konto usługi App Engine jest współdzielone przez więcej niż jedną 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 Cloud Firestoreagenta usługi.

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

   Otwórz Bazy danych

2. Wybierz z listy baz danych tę, której potrzebujesz.

3. W menu nawigacyjnym kliknij Import/Eksport.

4. Konto autoryzacji zobaczysz obok etykiety Zadania importu/eksportu są uruchamiane jako.

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 metod:

• Migracja projektu przez sprawdzenie i zaktualizowanie uprawnień do zasobnika Cloud Storage (zalecane).
• Dodaj ograniczenie wynikające z zasady obowiązującej w całej organizacji, które będzie mieć wpływ na wszystkie projekty w organizacji.

Pierwsza z tych technik jest preferowana, ponieważ ogranicza zakres efektu do jednego projektu Cloud Firestore. Druga technika nie jest zalecana, ponieważ nie przenosi uprawnień do istniejącego kosza Cloud Storage. Zapewnia jednak zgodność z wymaganiami dotyczącymi bezpieczeństwa na poziomie organizacji.

Migracja przez sprawdzenie i aktualizację uprawnień do zasobnika Cloud Storage

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

1. Zaktualizuj uprawnienia Cloud Storage zasobnika. Więcej informacji znajdziesz w następnej sekcji.
2. Potwierdź migrację do agenta usługi Cloud Firestore.

Uprawnienia agenta usługi do zasobnika

W przypadku operacji eksportu lub importu, które korzystają z zasobnika Cloud Storage w innym projekcie, musisz przyznać agentowi usługi Cloud Firestore uprawnienia do tego zasobnika. Na przykład operacje, które przenoszą dane do innego projektu, muszą mieć dostęp do zasobnika w tym projekcie. W przeciwnym razie po migracji do agenta usługi Cloud Firestore te operacje zakończą się niepowodzeniem.

Procesy importu i eksportu, które pozostają w tym samym projekcie, nie wymagają zmian uprawnień. Cloud Firestore Agent usługi ma domyślnie dostęp do zasobników w tym samym projekcie.

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

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

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

Przenoszenie projektu do agenta usługi Firestore

Aby przeprowadzić migrację 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 Bazy danych

2. Wybierz z listy baz danych tę, której potrzebujesz.

3. W menu nawigacyjnym kliknij Importowanie/eksportowanie.

4. Jeśli Twój projekt nie został jeszcze przeniesiony na konto usługi Cloud Firestore, zobaczysz baner z opisem migracji i przycisk Sprawdź stan zasobnika. Następny krok pomoże Ci zidentyfikować i naprawić potencjalne błędy uprawnień.

   Kliknij Sprawdź stan zasobnika.

   Pojawi się menu z opcją dokończenia migracji i listą Cloud Storage zasobników. 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 w projekcie. Nazwa agenta usługi pojawi się pod etykietą Agent usługi, któremu chcesz przyznać dostęp.

6. W przypadku każdego zasobnika na liście, którego będziesz używać w przyszłości do operacji importu lub eksportu, wykonaj te czynności:

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

   2. Kliknij Dodaj.
   3. W polu Nowe podmioty zabezpieczeń wpisz nazwę agenta usługi Cloud Firestore.
   4. W polu Wybierz rolę wybierz Agenci usług > Agent usługi Firestore.
   5. Kliknij Zapisz.
   6. Wróć na kartę ze stroną Cloud Firestore Import/eksport.
   7. Powtórz te czynności w przypadku pozostałych zasobników na liście. Pamiętaj, aby wyświetlić wszystkie strony listy.

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

   Gdy migracja się zakończy, otrzymasz alert. 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 z listy baz danych tę, której potrzebujesz.

3. W menu nawigacyjnym kliknij Import/Eksport.

4. Znajdź podmiot obok etykiety Zadania importu/eksportu są uruchamiane jako.

   Jeśli podmiotem zabezpieczeń jest service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, 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. Aby przeprowadzić migrację, zapoznaj się z artykułem Migracja do agenta usługi Firestore.

Dodawanie ograniczenia zasad na poziomie organizacji

• W zasadach organizacji ustaw to ograniczenie:

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

  To ograniczenie wymaga, aby operacje importowania i eksportowania korzystały z 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 zasady organizacji nie powoduje automatycznego przyznania agentowi usługi Cloud Firestore odpowiednich uprawnień do zasobnika Cloud Storage.

Jeśli ograniczenie powoduje błędy uprawnień w przypadku importowania lub eksportowania danych, możesz je wyłączyć, aby wrócić do korzystania z domyślnego konta usługi. Po sprawdzeniu i zaktualizowaniu Cloud Storageuprawnień do koszyka możesz ponownie włączyć ograniczenie.