Eksportowanie i importowanie danych

Możesz korzystać z usługi zarządzanego eksportu i importu Cloud Firestore, aby przywracać przypadkowo usunięte dane i eksportować dane do przetwarzania w trybie offline. Możesz wyeksportować wszystkie dokumenty lub tylko wybrane kolekcje. Podobnie możesz zaimportować wszystkie dane z 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 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 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. Tylko projekty Google Cloud z włączonymi płatnościami mogą korzystać z funkcji eksportowania i importowania.
2. Utwórz Cloud Storage zasobnik na potrzeby projektu w lokalizacji w pobliżu lokalizacji bazy danych.Cloud Firestore Nie możesz używać zasobnika „Płatnik żąda” do operacji eksportu i importu.

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 eksportowania i importowania oraz do dostępu do Cloud Storage:

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

   • Role: Owner lub Storage AdminCloud Storage

Uprawnienia agenta usługi

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

Agent usługi Cloud Firestore musi mieć dostęp do zasobnika Cloud Storage używanego w operacji eksportu lub importu. Jeśli TwójCloud Storage zasobnik znajduje się w tym samym projekcie co Cloud Firestorebaza danych, Cloud Firestoreagent usługi 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

Możesz użyć narzędzia wiersza poleceń gsutil, aby przypisać jedną z tych ról: Aby na przykład przypisać rolę administratora miejsca na dane 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 importowania i eksportowania 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. Wyświetl konto autoryzacji 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 Platform, klikając Cloud Shell.

  Rozpocznij Cloud Shell

  Sprawdź, czy gcloud jest skonfigurowany na potrzeby właściwego projektu:

  gcloud config set project [PROJECT_ID]
  

• Zainstaluj i zainicjuj pakiet Google Cloud SDK.

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 wykonywania operacji.

Eksportowanie wszystkich dokumentów

  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'

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 się nie powiedzie.

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

Przed wyeksportowaniem danych 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śniej niż earliestVersionTime. Jeśli w określonej sygnaturze czasowej nie ma już danych, 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 pliki eksportu będą w usłudze Cloud Storage, możesz zaimportować dokumenty z tych plików z powrotem do projektu lub do innego projektu. Weź pod uwagę te informacje o operacjach 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 korzystają z 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 go.

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

• Operacje importu nie aktywują funkcji w Cloud Functions. Detektory zrzutów otrzymują aktualizacje dotyczące operacji 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 taką samą nazwę plików 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 określonych kolekcji

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

Importowanie wyeksportowanego pliku 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 usługa Cloud Firestore przypisuje jej unikalną nazwę. Nazwy operacji możesz używać do usuwania, anulowania i sprawdzania stanu operacji.

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

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

Możesz jednak pominąć 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]

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ąć te dane, jeśli nie może ich oszacować.

• 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ępów, 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 eksportu pozostawi wyeksportowane dokumenty w Cloud Storage, a anulowanie 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]

Płatności 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 na stronie Cloud Firestorecennika. Operacje eksportu generują jedną operację odczytu na eksportowany dokument. Operacje importu powodują wykonanie 1 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 momentu ich zakończenia. Operacje eksportowania i importowania 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ą etykietę goog-firestoremanaged:exportimport do operacji, za które naliczane są opłaty. Na stronie raportów dotyczących 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 nakłada limit 10 000 kolumn na tabelę. Cloud Firestore operacje eksportu generują BigQuery schemat tabeliBigQuery dla każdej grupy kolekcji. W tym schemacie każda unikalna nazwa pola w grupie zbiorów staje się kolumną schematu.

Jeśli BigQuery schema grupy kolekcji przekracza 10 000 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 tys., możesz załadować dane do BigQuery, ale nie możesz wysyłać zapytań o pola podrzędne w polach mapy. Jeśli liczba kolumn nadal przekracza 10 000, operacja eksportu nie wygeneruje BigQuery schematu grupy kolekcji 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 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 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

Agent usługi Cloud Firestore jest preferowany, ponieważ jest 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 agenta usługi Cloud Firestore.

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

   Otwórz Bazy danych

2. Na liście baz danych wybierz odpowiednią bazę danych.

3. W menu nawigacyjnym kliknij Importowanie/eksportowanie.

4. Wyświetl konto autoryzacji 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 Cloud Storage uprawnień do zasobnika (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 istniejących uprawnień do 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 zasobnika Cloud Storage. Więcej informacji znajdziesz w następnej sekcji.
2. Potwierdź migrację do Cloud Firestore agenta usługi.

Uprawnienia agenta usługi do zasobnika

W przypadku wszystkich operacji eksportu lub importu, które korzystają z zasobnika Cloud Storagew innym projekcie, musisz przyznać Cloud Firestore agentowi usługi uprawnienia do tego zasobnika. Na przykład operacje przenoszące 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 nie powiodą się.

Procesy importu i eksportu w ramach tego samego projektu nie wymagają zmian uprawnień. Agent usługi Cloud Firestore ma domyślnie dostęp do zasobników w tym samym projekcie.

Zaktualizuj uprawnienia do zasobników Cloud Storage z innych projektów, aby przyznać dostęp agentowi usługi 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 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. Na liście baz danych wybierz odpowiednią bazę danych.

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 koszyków. Załadowanie listy może potrwać kilka minut.

   Ta lista zawiera zasobniki, które były niedawno 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łych operacjach 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 kroki w przypadku pozostałych zasobników na liście. Sprawdź wszystkie strony listy.

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

   Gdy migracja się zakończy, otrzymasz alert. Rozpoczętej migracji nie będzie 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. Na liście baz danych wybierz odpowiednią bazę danych.

3. W menu nawigacyjnym kliknij Importowanie/eksportowanie.

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, 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. Aby przeprowadzić migrację, zapoznaj się z artykułem Migracja do agenta usługi Firestore.

Dodawanie ograniczenia dotyczącego zasad obowiązujących w całej 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 Cloud Firestoreagenta usługi do autoryzowania żądań. Aby ustawić to ograniczenie, zapoznaj się z artykułem Tworzenie zasad organizacji i zarządzanie nimi .

Zastosowanie tego ograniczenia zasady organizacji nie przyznaje automatycznie odpowiednich uprawnień do zasobnika Cloud Storage agentowi usługi Cloud Firestore.

Jeśli ograniczenie powoduje błędy uprawnień w przypadku 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ń do koszyka możesz ponownie włączyć ograniczenie.Cloud Storage