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 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ć eksporty Cloud Firestore do BigQuery.

Na tej stronie opisano, jak eksportować i importować dokumenty Cloud Firestore za pomocą zarządzanej usługi eksportu i importu oraz Cloud Storage. Zarządzana usługa eksportu i importu 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 zarządzanej usługi eksportu i importu, musisz wykonać te czynności:

1. Włącz płatności w projekcie Google Cloud. Funkcji eksportowania i importowania można używać tylko w projektach Google Cloud z włączonymi płatnościami.
2. Utwórz zasobnik Cloud Storage dla projektu w lokalizacji bliskiej lokalizacji bazy danych Cloud Firestore. Do operacji eksportu i importu nie można używać zasobnika Płatność po stronie żądającego ani zasobnika Rapid.

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ą uprawnienia niezbędne do operacji eksportu i importu oraz dostępu do Cloud Storage:

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

   • Role Cloud Storage: Owner lub Storage Admin

Uprawnienia agenta usługi

Operacje eksportu i importu używają agenta usługi Cloud Firestore do autoryzacji operacji Cloud Storage. Agent usługi Cloud Firestore używa tej konwencji 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 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ć 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 poniższych ról. Aby na przykład przypisać rolę administratora pamięci masowej 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 jest używany do nadawania nazwy agentowi usługi Cloud Firestore. 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

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 baza danych używa agenta usługi Cloud Firestore czy starszego konta usługi App Engine.

1. Wyświetl konto autoryzacji obok etykiety Zadania importu/eksportu są uruchamiane jako.

Agent usługi musi mieć rolę Storage Admin w zasobniku Cloud Storage, który ma być używany do operacji eksportu lub importu.

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 na jeden z tych sposobów:

• Uzyskaj dostęp do gcloud z konsoli Google Cloud za pomocą Cloud Shell.

  Rozpocznij Cloud Shell

  Sprawdź, czy narzędzie gcloud jest skonfigurowane dla właściwego projektu:

  gcloud config set project [PROJECT_ID]
  

• Zainstaluj i zainicjuj pakiet SDK Google Cloud.

Eksportuj dane

Operacja eksportowania kopiuje dokumenty z bazy danych do zbioru plików w zasobniku Cloud Storage. Pamiętaj, że eksport nie jest dokładną migawką bazy danych wykonaną 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 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 wyeksportować dane PITR, których sygnatura czasowa jest sygnaturą czasową pełnej minuty w ciągu ostatnich 7 dni, ale nie wcześniej niż earliestVersionTime. Jeśli dane nie istnieją już w określonej sygnaturze czasowej, operacja eksportu się nie powiedzie.

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:

• Określ sygnaturę czasową w formacie RFC 3339. Na przykład: 2023-05-26T10:20:00.00Z.
• Upewnij się, że podany znacznik czasu jest znacznikiem czasu pełnej minuty w ciągu ostatnich 7 dni, ale nie wcześniejszym niż earliestVersionTime. Jeśli dane nie istnieją już w określonej sygnaturze czasowej, generowany jest 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 masz pliki eksportu w 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 bazy danych. Eksport nie zawiera definicji indeksów.

• Importowanie nie powoduje przypisania nowych identyfikatorów dokumentów. Importy używają identyfikatorów przechwyconych 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 zastąpi istniejący dokument.

• Jeśli import nie ma wpływu na dokument w bazie danych, pozostanie on w niej po zakończeniu importu.

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

• Przed importem nie należy dodawać nowych dokumentów Cloud Firestore, których nie było w oryginalnych plikach wyjściowych eksportu, ani usuwać żadnych istniejących dokumentów z plików GCS. Jeśli to zrobisz, import się nie powiedzie.

• 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 te same nazwy 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 grup kolekcji

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

Importowanie eksportu PITR

Aby zaimportować wyeksportowaną bazę danych, wykonaj czynności opisane w sekcji Importowanie wszystkich dokumentów. Jeśli w bazie danych znajduje się 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ę. Możesz użyć nazwy operacji, aby ją usunąć, anulować lub sprawdzić jej stan.

Nazwy operacji są poprzedzone prefiksem projects/[PROJECT_ID]/databases/(default)/operations/, na przykład:

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

Możesz jednak pominąć prefiks, gdy podajesz nazwę operacji w poleceniach 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]

Oszacowanie czasu ukończenia

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

• workEstimated pokazuje szacowaną łączną liczbę bajtów i dokumentów, które zostaną przetworzone w ramach operacji. Cloud Firestore może pominąć te dane, jeśli nie może oszacować wartości.

• workCompleted pokazuje 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 przetworzone. Może ona być większa niż wartość workEstimated.

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

Anulowanie operacji

gcloud firestore operations cancel [OPERATION_NAME]

Anulowanie wykonywanej operacji nie powoduje jej cofnięcia. Anulowanie operacji eksportu spowoduje, że dokumenty, które zostały już wyeksportowane, pozostaną w Cloud Storage, a anulowanie operacji importu spowoduje, że zmiany, które zostały już wprowadzone w bazie danych, pozostaną na miejscu. Nie możesz zaimportować częściowo ukoń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 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 eksportu i importu są rozliczane za odczyty i zapisy dokumentów według stawek podanych w cenniku Cloud Firestore. Operacje eksportu powodują jedną operację odczytu na każdy wyeksportowany dokument. Operacje importu powodują wykonanie 1 operacji zapisu na każdy zaimportowany dokument.

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

Operacje eksportu lub importu nie będą wywoływać alertów dotyczących budżetu Google Cloud, dopóki nie zostaną zakończone. Operacje eksportu i importu nie mają 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 rozliczanych. Na stronie raportów rozliczeniowych 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 określono filtr collection-ids. Zobacz Wczytywanie danych z eksportów Cloud Firestore.

Limit kolumn: BigQuery

BigQuery nakłada limit 10 000 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 000 kolumn,operacja eksportu Cloud Firestore próbuje utrzymać liczbę kolumn poniżej limitu, 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ń do podpól w polach mapy. Jeśli liczba kolumn nadal przekracza 10 000, operacja eksportu nie generuje schematu BigQuery dla grupy kolekcji i nie można wczytać jej danych do BigQuery.

Format eksportu i pliki metadanych

Dane wyjściowe zarządzanego eksportu używają formatu logu 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łu, które można dekodować za pomocą kompilatora protokołu protoc. Możesz na przykład zdekodować plik metadanych, aby określić grupy kolekcji, które zawierają wyeksportowane pliki:

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:

Agent usługi Cloud Firestore

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

Usługa Cloud Firestore używała wcześniej domyślnego konta usługi App Engine zamiast 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 podanych w tej sekcji, aby przejść na 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 dla Cloud Firestore. Konto usługi App Engine jest współdzielone przez więcej niż 1 usługę.

Wyświetlanie konta autoryzacji

Na stronie Import/eksport w konsoli Google Cloud możesz sprawdzić, które konto jest używane przez operacje importu i eksportu 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 stronę Bazy danych

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

3. W menu nawigacyjnym kliknij Import/Export (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:

• Przenieś projekt, sprawdzając i aktualizując uprawnienia zasobnika Cloud Storage (zalecane).
• Dodaj ograniczenie wynikające z zasady obowiązującej w całej organizacji, które ma wpływ na wszystkie projekty w organizacji.

Pierwsza z tych technik jest preferowana, ponieważ ogranicza zakres efektu do pojedynczego projektu Cloud Firestore. Druga technika nie jest zalecana, ponieważ nie powoduje migracji istniejących uprawnień zasobnika Cloud Storage. Zapewnia jednak zgodność z zasadami bezpieczeństwa na poziomie organizacji.

Przeprowadź migrację, sprawdzając i aktualizując uprawnienia zasobnika Cloud Storage

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

1. Zaktualizuj uprawnienia zasobnika Cloud Storage. Szczegółowe informacje 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 nie będą działać.

Przepływy pracy importu i eksportu, które pozostają w tym samym projekcie, nie wymagają zmian uprawnień. Agent usługi Cloud Firestore może domyślnie uzyskiwać 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ć uprawnienia tylko do odczytu lub tylko do zapisu, użyj roli niestandardowej.

Proces migracji opisany w następnej sekcji pomoże Ci 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 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 Import/Export (Importowanie/eksportowanie).

4. Jeśli Twój projekt nie został jeszcze przeniesiony do agenta 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ą zakończenia migracji i listą zasobników Cloud Storage. Wczytanie 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 dają 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ć do przyszłych operacji importu lub eksportu, wykonaj te czynności:

   1. W wierszu tabeli tego zasobnika 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 Agenty usługi > Agent usługi Firestore.
   5. Kliknij Zapisz.
   6. Wróć do karty ze stroną importu/eksportu Cloud Firestore.
   7. Powtórz te czynności w przypadku innych zasobników na liście. Pamiętaj, aby przejrzeć wszystkie strony listy.

7. Kliknij Przenieś do agenta usługi Firestore. Jeśli nadal masz zasobniki, w przypadku których nie udało się sprawdzić uprawnień, musisz potwierdzić migrację, klikając Migruj.

   Po zakończeniu migracji 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 stronę Bazy danych

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

3. W menu nawigacyjnym kliknij Import/Export (Importowanie/eksportowanie).

4. Znajdź podmiot zabezpieczeń 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 dokończyć migrację, zapoznaj się z artykułem Migracja do agenta usługi Firestore.

Dodawanie ograniczenia zasad na poziomie organizacji

• Ustaw w zasadach organizacji to ograniczenie:

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

  To ograniczenie wymaga, aby operacje importu i eksportu używały agenta usługi Cloud Firestore do autoryzowania żą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ń 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ń zasobnika Cloud Storage możesz ponownie włączyć ograniczenie.