Check out what’s new from Firebase at Google I/O 2022. Learn more

Eksportuj i importuj dane

Możesz użyć zarządzanej usługi eksportu i importu Cloud Firestore, aby odzyskać dane po przypadkowym usunięciu i wyeksportować dane do przetwarzania 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ć eksporty z Cloud Firestore do BigQuery .

Na tej stronie opisano, jak eksportować i importować dokumenty Cloud Firestore przy użyciu zarządzanej usługi eksportu i importu oraz Cloud Storage . Usługa zarządzanego eksportu i importu Cloud Firestore jest dostępna za pośrednictwem narzędzia wiersza poleceń gcloud i interfejsu Cloud Firestore API ( REST , RPC ).

Zanim zaczniesz

Aby móc korzystać z zarządzanej usługi eksportowania i importowania, należy wykonać następujące zadania:

  1. Włącz płatności za projekt Google Cloud. Tylko projekty Google Cloud z włączonymi płatnościami mogą korzystać z funkcji eksportu i importu.
  2. Utwórz zasobnik Cloud Storage dla swojego projektu w lokalizacji w pobliżu lokalizacji bazy danych Cloud Firestore . Nie można używać zasobnika wnioskodawca płaci do operacji eksportu i importu.
  3. Upewnij się, że 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 następujące role przyznają niezbędne uprawnienia do operacji eksportu i importu oraz dostępu do Cloud Storage:

    • Role Cloud Firestore: Owner , właściciel Cloud Datastore Owner lub Cloud Datastore Import Export Admin
    • Role Cloud Storage: Owner lub Storage Admin

Domyślne uprawnienia konta usługi

Każdy projekt Google Cloud automatycznie tworzy domyślne konto usługi o nazwie PROJECT_ID @appspot.gserviceaccount.com . Operacje eksportu i importu używają tego konta usługi do autoryzacji operacji Cloud Storage.

Domyślne konto usługi Twojego projektu wymaga dostępu do zasobnika Cloud Storage używanego w operacji eksportu lub importu. Jeśli Twój zasobnik Cloud Storage znajduje się w tym samym projekcie co baza danych Cloud Firestore, domyślne konto usługi ma domyślnie dostęp do zasobnika .

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

Konto usługi wymaga roli Storage Admin dla zasobnika Cloud Storage, który ma być używany do operacji eksportowania lub importowania.

Jeśli wyłączysz lub usuniesz domyślne konto usługi App Engine, Twoja aplikacja App Engine utraci dostęp do bazy danych Cloud Firestore. Jeśli wyłączyłeś konto usługi App Engine, możesz je ponownie włączyć, patrz włączanie konta usługi . Jeśli usunąłeś konto usługi App Engine w ciągu ostatnich 30 dni, możesz je przywrócić, patrz Przywracanie konta usługi .

Skonfiguruj gcloud dla swojego projektu

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

Eksportuj dane

Operacja eksportu kopiuje dokumenty z Twojej bazy danych do zestawu plików w zasobniku Cloud Storage. Należy zauważyć, ż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.

Eksportuj wszystkie dokumenty

Konsola Google Cloud

  1. Przejdź do strony Import/Eksport Cloud Firestore w konsoli Google Cloud Platform.

    Przejdź do strony Import/Eksport

  2. Kliknij Eksportuj .

  3. Kliknij opcję Eksportuj całą bazę danych .

  4. W polu Wybierz miejsce docelowe wpisz nazwę zasobnika Cloud Storage lub użyj przycisku Przeglądaj , aby wybrać zasobnik.

  5. Kliknij Eksportuj .

Konsola powraca do strony Import/Eksport . Jeśli operacja rozpocznie się pomyślnie, strona doda wpis do strony ostatnich importów i eksportów. W przypadku niepowodzenia strona wyświetla komunikat o błędzie.

gcloud

Użyj polecenia firestore export firestore, aby wyeksportować wszystkie dokumenty z bazy danych, zastępując [BUCKET_NAME] nazwą swojego zasobnika Cloud Storage. Dodaj flagę --async , aby narzędzie gcloud nie czekało na zakończenie operacji.

gcloud firestore export gs://[BUCKET_NAME]

Możesz uporządkować swoje eksporty, dodając prefiks pliku po nazwie zasobnika, na przykład BUCKET_NAME/my-exports-folder/export-name . Jeśli nie podasz prefiksu pliku, usługa zarządzanego eksportu utworzy go na podstawie bieżącego znacznika czasu.

Po rozpoczęciu operacji eksportu zamknięcie terminala nie anuluje operacji, patrz anulowanie operacji .

Eksportuj określone kolekcje

Konsola Google Cloud

  1. Przejdź do strony Import/Eksport Cloud Firestore w konsoli Google Cloud Platform.

    Przejdź do strony Import/Eksport

  2. Kliknij Eksportuj .

  3. Kliknij opcję Eksportuj jedną lub więcej grup kolekcji . Użyj menu rozwijanego, aby wybrać jedną lub więcej grup kolekcji.

  4. W polu Wybierz miejsce docelowe wpisz nazwę zasobnika Cloud Storage lub użyj przycisku Przeglądaj , aby wybrać zasobnik.

  5. Kliknij Eksportuj .

Konsola powraca do strony Import/Eksport . Jeśli operacja rozpocznie się pomyślnie, strona doda wpis do strony ostatnich importów i eksportów. W przypadku niepowodzenia strona wyświetla komunikat o błędzie.

gcloud

Aby wyeksportować określone grupy kolekcji, użyj flagi --collection-ids . Operacja eksportuje tylko grupy kolekcji o podanych identyfikatorach kolekcji. Grupa kolekcji obejmuje wszystkie kolekcje i podkolekcje (w dowolnej ścieżce) o określonym identyfikatorze kolekcji.

gcloud firestore export gs://[BUCKET_NAME] --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1]

Zaimportować dane

Po wyeksportowaniu plików w Cloud Storage możesz zaimportować dokumenty z tych plików z powrotem do swojego projektu lub do innego projektu. Zwróć uwagę na następujące punkty dotyczące operacji importowania:

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

  • Importy nie przypisują nowych identyfikatorów dokumentów. Importy wykorzystują identyfikatory przechwycone w momencie eksportu. Gdy dokument jest importowany, jego identyfikator jest zarezerwowany, aby zapobiec kolizjom identyfikatorów. Jeśli dokument o tym samym identyfikatorze już istnieje, import nadpisuje istniejący dokument.

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

  • Operacje importu nie uruchamiają Cloud Functions. Detektory migawek otrzymują aktualizacje związane z operacjami importu.

  • Nazwa pliku .overall_export_metadata musi być zgodna z nazwą jego 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 .

Importuj wszystkie dokumenty z eksportu

Konsola Google Cloud

  1. Przejdź do strony Import/Eksport Cloud Firestore w konsoli Google Cloud Platform.

    Przejdź do strony Import/Eksport

  2. Kliknij Importuj .

  3. W polu Nazwa pliku wprowadź nazwę pliku .overall_export_metadata z zakończonej operacji eksportu. Możesz użyć przycisku Przeglądaj , aby wybrać plik.

  4. Kliknij Importuj .

Konsola powraca do strony Import/Eksport . Jeśli operacja rozpocznie się pomyślnie, strona doda wpis do strony ostatnich importów i eksportów. W przypadku niepowodzenia strona wyświetla komunikat o błędzie.

gcloud

Użyj polecenia firestore import , aby zaimportować dokumenty z poprzedniej operacji eksportu.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

gdzie [BUCKET_NAME] i [EXPORT_PREFIX] wskazują lokalizację plików eksportu. Na przykład:

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

Możesz potwierdzić lokalizację plików eksportu w przeglądarce Cloud Storage w konsoli Google Cloud Platform:

Otwórz przeglądarkę Cloud Storage

Po rozpoczęciu operacji importu zamknięcie terminala nie anuluje operacji, patrz anulowanie operacji .

Importuj określone kolekcje

Konsola Google Cloud

Nie możesz wybrać konkretnych kolekcji w konsoli. Zamiast tego użyj gcloud .

gcloud

Aby zaimportować określone grupy kolekcji z zestawu plików eksportu, użyj flagi --collection-ids . Operacja importuje tylko grupy kolekcji o podanych identyfikatorach kolekcji. Grupa kolekcji obejmuje wszystkie kolekcje i podkolekcje (w dowolnej ścieżce) o określonym identyfikatorze kolekcji.

Tylko eksport określonych grup kolekcji obsługuje import określonych grup kolekcji. Nie można importować określonych kolekcji z eksportu wszystkich dokumentów.

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

Zarządzanie operacjami eksportu i importu

Po rozpoczęciu operacji eksportowania lub importowania Cloud Firestore przypisuje tej operacji unikalną nazwę. Możesz użyć nazwy operacji, aby usunąć, anulować lub sprawdzić status operacji.

Nazwy operacji mają przedrostek projects/[PROJECT_ID]/databases/(default)/operations/ , na przykład:

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

Można jednak pominąć prefiks podczas określania nazwy operacji dla poleceń describe , cancel i delete .

Wymień wszystkie operacje eksportu i importu

Konsola Google Cloud

Listę ostatnich operacji eksportowania i importowania możesz wyświetlić na stronie Import/Eksport Cloud Firestore w konsoli Google Cloud Platform.

Przejdź do strony Import/Eksport

gcloud

Użyj polecenia operations list aby wyświetlić wszystkie uruchomione i ostatnio zakończone operacje eksportu i importu:

gcloud firestore operations list

Sprawdź stan pracy

Konsola Google Cloud

Stan ostatniej operacji eksportu lub importu możesz wyświetlić na stronie Import/Eksport Cloud Firestore w konsoli Google Cloud Platform.

Przejdź do strony Import/Eksport

gcloud

Użyj polecenia operations describe aby wyświetlić stan operacji eksportu lub importu.

gcloud firestore operations describe [OPERATION_NAME]

Oszacuj czas realizacji

Żądanie stanu długotrwałej operacji zwraca metryki workEstimated i workCompleted . Każda z tych metryk jest zwracana zarówno w liczbie bajtów, jak i liczbie jednostek:

  • workEstimated pokazuje szacowaną całkowitą liczbę bajtów i dokumentów, które operacja będzie przetwarzać.

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

Podziel workCompleted przez workEstimated dla przybliżonego oszacowania postępu. To oszacowanie może być niedokładne, ponieważ zależy od opóźnionego zbierania statystyk.

Anuluj operację

Konsola Google Cloud

Możesz anulować trwającą operację eksportu lub importu na stronie Import/Eksport Cloud Firestore w konsoli Google Cloud Platform.

Przejdź do strony Import/Eksport

W tabeli Ostatnie importy i eksporty aktualnie wykonywane operacje zawierają przycisk Anuluj w kolumnie Ukończono . Kliknij przycisk Anuluj , aby zatrzymać operację. Przycisk zmieni się na komunikat Anulowanie , a następnie na Anulowano , gdy operacja zostanie całkowicie zatrzymana.

gcloud

Użyj polecenia operations cancel aby zatrzymać trwającą operację:

gcloud firestore operations cancel [OPERATION_NAME]

Anulowanie uruchomionej operacji nie cofa operacji. Anulowana operacja eksportu pozostawi dokumenty już wyeksportowane w Cloud Storage, a anulowana operacja importu pozostawi aktualizacje już wprowadzone do Twojej bazy danych. Nie można zaimportować częściowo zakończonego eksportu.

Usuń operację

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

gcloud firestore operations delete [OPERATION_NAME]

Rozliczenia i ceny za operacje eksportowe i importowe

Przed użyciem zarządzanej usługi eksportu i importu musisz włączyć rozliczenia za projekt Google Cloud. Operacje eksportu i importu są naliczane za odczyty i zapisy dokumentów według stawek podanych w cenniku Cloud Firestore .

Koszty operacji eksportowych i importowych nie wliczają się do Twojego limitu wydatków . Operacje eksportu lub importu nie spowodują wyzwolenia alertów budżetu Google Cloud do czasu ich zakończenia. Podobnie odczyty i zapisy wykonane podczas operacji eksportu lub importu są stosowane do przydziału dziennego po zakończeniu operacji. Operacje eksportu i importu nie wpłyną na użycie widoczne w sekcji użycia konsoli.

Przeglądanie kosztów eksportu i importu

Operacje eksportu i importu stosują etykietę goog-firestoremanaged:exportimport do rozliczanych operacji. Na stronie raportów Cloud Billing możesz użyć tej etykiety, aby wyświetlić koszty związane z operacjami importu i eksportu:

Uzyskaj dostęp do etykiety zarządzanej goog-firestore z menu filtrów.

Eksportuj do BigQuery

Możesz wczytać dane z eksportu Cloud Firestore do BigQuery, ale tylko wtedy, gdy określisz filtr collection-ids . Zobacz Ładowanie danych z eksportów Cloud Firestore .

Limit kolumn BigQuery

BigQuery narzuca limit 10 000 kolumn na tabelę. Operacje eksportu Cloud Firestore generują schemat tabeli BigQuery dla każdej grupy kolekcji. W tym schemacie każda unikatowa 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 zmieścić się w limicie kolumn, traktując pola mapy jako bajty. Jeśli ta konwersja spowoduje, że liczba kolumn spadnie poniżej 10 000, możesz załadować dane do BigQuery, ale nie możesz wysyłać zapytań do pól podrzędnych w polach mapy. Jeśli liczba kolumn nadal przekracza 10 000, operacja eksportu nie generuje schematu BigQuery dla grupy kolekcji i nie możesz wczytać jej danych do BigQuery.

Format eksportu i pliki metadanych

Dane wyjściowe zarządzanego eksportu korzystają z formatu dziennika LevelDB .

Pliki metadanych

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

Pliki metadanych są buforami protokołów i można je dekodować za pomocą kompilatora protokołów protoc . Na przykład możesz zdekodować plik metadanych, aby określić grupy kolekcji, które zawierają pliki eksportu:

protoc --decode_raw < export0.export_metadata

Migracja agenta usług

Możesz teraz używać agenta usługi Cloud Firestore do autoryzowania operacji importowania i eksportowania zamiast konta usługi App Engine. Agent usługi i konto usługi używają następujących konwencji nazewnictwa:

Agent usługi Cloud Firestore
service- project_number @gcp-sa-firestore.iam.gserviceaccount.com
Konto usługi App Engine
project_id @appspot.gserviceaccount.com

Preferowany jest agent usługi Cloud Firestore, ponieważ jest on specyficzny dla Cloud Firestore. Konto usługi App Engine jest współużytkowane przez więcej niż jedną usługę.

Wyświetl konto autoryzacyjne

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

  1. Przejdź do strony Import/Eksport Cloud Firestore w konsoli Google Cloud Platform.

    Przejdź do importu/eksportu

  2. Wyświetl konto autoryzacji obok zadań importu/eksportu uruchamianych jako etykieta.

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

Pierwsza z tych technik jest preferowana, ponieważ lokalizuje zakres efektu do jednego projektu Cloud Firestore. Druga technika nie jest preferowana, ponieważ nie przenosi istniejących uprawnień zasobnika Cloud Storage. Zapewnia jednak zgodność w zakresie bezpieczeństwa na poziomie organizacji.

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

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

  1. Zaktualizuj uprawnienia zasobnika Cloud Storage. Szczegółowe informacje znajdują się w następnej sekcji.
  2. Potwierdź migrację do agenta usługi Cloud Firestore.

Uprawnienia zasobnika agenta usług

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

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

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

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

Proces migracji opisany w poniższej sekcji pomaga zidentyfikować zasobniki Cloud Storage, które mogą wymagać aktualizacji uprawnień.

Przenieś projekt do Firestore Service Agent

Wykonaj poniższe czynności, aby przeprowadzić migrację z konta usługi App Engine do agenta usługi Cloud Firestore. Po zakończeniu migracji nie można cofnąć.

  1. Przejdź do strony Import/Eksport Cloud Firestore w konsoli Google Cloud Platform.

    Przejdź do importu/eksportu

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

    Kliknij opcję Sprawdź stan zasobnika .

    Pojawi się menu z opcją zakończenia migracji i listą zasobników Cloud Storage. Wczytywanie listy może potrwać kilka minut.

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

  3. Zanotuj główną nazwę agenta usługi Cloud Firestore w Twoim projekcie. Nazwa agenta usługi pojawia się pod agentem usługi, aby umożliwić dostęp do etykiety.
  4. W przypadku dowolnego zasobnika na liście, którego będziesz używać do przyszłych operacji importowania lub eksportowania, wykonaj następujące 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 Nowi zleceniodawcy wprowadź nazwę agenta usługi Cloud Firestore.
    4. W polu Wybierz rolę wybierz Agenci usług > Agent usługi Firestore .
    5. Kliknij Zapisz .
    6. Wróć do karty ze stroną importu/eksportu Cloud Firestore.
    7. Powtórz te kroki dla innych zasobników na liście. Upewnij się, że przeglądasz wszystkie strony listy.
  5. Kliknij opcję Migruj do agenta usługi Firestore . Jeśli nadal masz zasobniki, których sprawdzenie uprawnień nie powiodło się, musisz potwierdzić migrację, klikając Migruj .

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

Wyświetl stan migracji

  1. Aby sprawdzić stan migracji projektu, przejdź do strony Import/Eksport w konsoli Google Cloud Platform:

    Przejdź do importu/eksportu

  2. Poszukaj podmiotu zabezpieczeń obok zadań importu/eksportu uruchamianych jako etykieta.

    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. Zobacz Migracja do agenta usługi Firestore, aby zakończyć migrację.

Dodaj ograniczenie zasad obowiązujące w całej organizacji

  • Ustaw następujące ograniczenie w zasadach organizacji:

    Wymagaj agenta usługi Firestore do importu/eksportu ( 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, zobacz Tworzenie i zarządzanie zasadami organizacji .

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

Jeśli ograniczenie powoduje błędy uprawnień dla 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.