Eksportowanie i importowanie danych

Usługa zarządzanego eksportu i importu w Cloud Firestore pozwala na odzyskiwanie danych po przypadkowym usunięciu danych oraz ich eksportowanie w trybie offline. Możesz wyeksportować wszystkie dokumenty lub tylko wybrane kolekcje. W podobny sposób 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. Możesz też wczytać eksporty z Cloud Firestore do BigQuery.

Na tej stronie dowiesz się, jak eksportować i importować dokumenty Cloud Firestore za pomocą usługi zarządzanego eksportu i importu oraz Cloud Storage. Zarządzana usługa eksportu i importu w Cloud Firestore jest dostępna za pomocą narzędzia wiersza poleceń gcloud oraz interfejsu Cloud Firestore API (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 za projekt Google Cloud. Funkcji eksportowania i importowania można używać tylko w projektach Google Cloud, w których włączono płatności.
2. Utwórz zasobnik Cloud Storage dla swojego projektu w lokalizacji w pobliżu lokalizacji bazy danych Cloud Firestore. Nie możesz używać zasobnika Żądający płaci na potrzeby 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 eksportu i importu oraz dostęp do Cloud Storage:

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

   • Role w Cloud Storage: Owner lub Storage Admin

Uprawnienia agenta usługi

Operacje eksportu i importu używają agenta usługi Cloud Firestore do autoryzacji operacji w 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 domyślnie ma do niego dostęp.

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

Przypisz role do agenta usługi

Za pomocą narzędzia wiersza poleceń gsutil możesz przypisać jedną z poniższych ról. 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 GCP.

Wyświetl nazwę agenta usługi

Konto używane przez operacje importu i eksportu do autoryzowania żądań możesz wyświetlić na stronie Import/eksport w konsoli Google Cloud Platform. Możesz też sprawdzić, czy Twoja baza danych używa agenta usługi Cloud Firestore czy starszej wersji konta usługi App Engine.

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

Agent usługi wymaga roli Storage Admin, aby zasobnik Cloud Storage był używany w operacji eksportu lub importu.

Skonfiguruj usługę gcloud w projekcie

Operacje importowania i eksportowania możesz zainicjować za pomocą konsoli Google Cloud Platform lub narzędzia wiersza poleceń gcloud. Aby użyć gcloud, skonfiguruj narzędzie wiersza poleceń i połącz się z projektem na jeden z tych sposobów:

• Uzyskaj dostęp do usługi gcloud z poziomu konsoli Google Cloud Platform za pomocą Cloud Shell.

  Uruchamianie Cloud Shell

  Sprawdź, czy usługa gcloud jest skonfigurowana dla właściwego projektu:

  gcloud config set project [PROJECT_ID]
  

• Zainstaluj i zainicjuj pakiet SDK Google Cloud.

Eksportuj dane

Operacja eksportu kopiuje dokumenty 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 Cloud Storage z danych PTR za pomocą polecenia gcloud firestore export. Możesz eksportować dane o PITR, gdzie sygnatura czasowa to pełna minuta z ostatnich 7 dni, ale nie wcześniej 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, określając parametr snapshot-time do żądanej sygnatury czasowej przywracania.

   gcloud

   Aby wyeksportować bazę danych do zasobnika, uruchom to polecenie.

   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.

   Przed wyeksportowaniem danych PITR weź pod uwagę te informacje:

   • Podaj sygnaturę czasową 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ążymy Cię płatnością za nieudany eksport PITR.

importowanie danych,

Po wyeksportowaniu plików w Cloud Storage możesz zaimportować zawarte w nich dokumenty z powrotem do swojego lub innego projektu. Zwróć uwagę na te informacje dotyczące operacji importu:

• Podczas importowania danych wymagane indeksy są aktualizowane na podstawie aktualnych definicji indeksów w bazie danych. Wyeksportowane dane nie zawierają definicji indeksów.

• Importy nie powodują przypisania nowych identyfikatorów dokumentów. Import korzysta z identyfikatorów zapisanych w momencie eksportu. Identyfikator dokumentu jest zarezerwowany podczas importowania, aby zapobiec kolizji ze sobą. Jeśli dokument o tym samym identyfikatorze już istnieje, import zastępuje istniejący dokument.

• Jeśli import nie ma wpływu na dokument w bazie danych, pozostanie on w bazie danych 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ć taka sama jak nazwa jego 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'

Importuj określone kolekcje

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

Importowanie eksportu PITR

Wykonaj czynności opisane w artykule Importowanie wszystkich dokumentów, aby zaimportować eksportowaną bazę danych. Jeśli jakikolwiek dokument istnieje już w bazie danych, zostanie zastąpiony.

zarządzanie operacjami eksportu i importu;

Gdy rozpoczniesz operację eksportu lub importu, Cloud Firestore przypisze operacji unikalną nazwę. Możesz użyć tej nazwy operacji, aby ją usunąć, anulować lub sprawdzić stan.

Nazwy operacji 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

Sprawdź stan operacji

gcloud firestore operations describe [OPERATION_NAME]

Oszacuj czas realizacji

Żądanie dotyczące stanu długo trwającej operacji zwraca wskaźniki workEstimated i workCompleted. Każdy z tych wskaźników jest zwracany zarówno w liczbie bajtów, jak i w liczbie encji:

• workEstimated pokazuje szacowaną łączną liczbę bajtów i dokumentów, które zostaną przetworzone przez operację. Cloud Firestore może pominąć ten wskaźnik, jeśli nie może dokonać oszacowania.

• 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 uruchomionej operacji nie powoduje jej cofnięcia. Anulowana operacja eksportu pozostawi dokumenty już wyeksportowane do Cloud Storage, a anulowana operacja importu nie spowoduje zmian wprowadzonych w bazie danych. Nie można zaimportować częściowo ukończonego eksportu.

Usuwanie operacji

Użyj polecenia gcloud firestore operations delete, aby usunąć operację z listy ostatnich operacji. 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.

Opłaty za odczyty i zapisy dokumentów są naliczane za operacje eksportu i importu według stawek podanych w cenniku Cloud Firestore. Operacje eksportu wymagają 1 operacji odczytu na wyeksportowany dokument. Operacje importu wymagają wykonania 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.

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 też odczyty i zapisy wykonane podczas operacji eksportu lub importu są stosowane do limitu dziennego po zakończeniu tej operacji. 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 rozliczanych operacji. Na stronie raportów dotyczących Rozliczeń usługi Google Cloud możesz za pomocą tej etykiety wyświetlać koszty związane z operacjami importu i eksportu:

Eksportuj do BigQuery

Możesz wczytywać do BigQuery dane z eksportu Cloud Firestore, ale tylko wtedy, gdy określisz filtr collection-ids. Zapoznaj się z sekcją Wczytywanie danych z eksportów Cloud Firestore.

Limit kolumn BigQuery

BigQuery nakłada limit 10 000 kolumn na tabelę. Operacje eksportu w 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 przekroczy 10 000 kolumn,operacja eksportu Cloud Firestore spróbuje zmieścić się w limicie kolumn, traktując pola mapy jako bajty. Jeśli w ramach tej konwersji liczba kolumn spadnie poniżej 10 000, możesz wczytać dane do 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 000, operacja eksportu nie wygeneruje schematu BigQuery dla grupy kolekcji i nie będzie można wczytać 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 grupy kolekcji. 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

Zamiast konta usługi App Engine do autoryzowania operacji importu i eksportu Cloud Firestore używa agenta usługi Cloud Firestore. 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

Dotychczas Cloud Firestore używał 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 opisanych w tej sekcji, aby przejść na agenta usługi Cloud Firestore.

Konto usługi App Engine

PROJECT_ID@appspot.gserviceaccount.com

Agent usługi Cloud Firestore jest zalecany, ponieważ jest specyficzny dla Cloud Firestore. Konto usługi App Engine jest współdzielone przez więcej niż jedną usługę.

Wyświetl konto autoryzacji

Na stronie Import/eksport w konsoli Google Cloud Platform 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 Platform 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 przeprowadzić migrację do agenta usługi Cloud Firestore przy użyciu jednej z tych technik:

• Przeprowadź migrację projektu przez sprawdzenie i zaktualizowanie uprawnień zasobnika Cloud Storage (zalecane).
• Dodaj ograniczenie zasad dla całej organizacji, które ma wpływ na wszystkie projekty w organizacji.

Preferowana jest pierwsza z tych technik, ponieważ lokalizuje zakres skutków do pojedynczego projektu Cloud Firestore. Druga metoda nie jest preferowana, ponieważ nie przenosi istniejących uprawnień zasobników Cloud Storage. Zapewnia jednak zgodność zabezpieczeń na poziomie organizacji.

Przeprowadź migrację przez sprawdzenie i zaktualizowanie 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ę do agenta usługi Cloud Firestore.

Uprawnienia do zasobnika agenta usługi

W przypadku wszelkich operacji eksportu lub importu, które korzystają z zasobnika Cloud Storage w innym projekcie, musisz przyznać uprawnienia agenta usługi Cloud Firestore do 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 po migracji do agenta usługi Cloud Firestore zakończą się niepowodzeniem.

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

Zaktualizuj uprawnienia 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 zapewnia 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 tej sekcji 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 poniższe czynności. Po zakończeniu migracji nie można jej cofnąć.

1. W konsoli Google Cloud Platform 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. 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 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 przyznają agentowi usługi Cloud Firestore uprawnień do odczytu ani zapisu.

5. Zanotuj nazwę podmiotu zabezpieczeń agenta usługi Cloud Firestore w Twoim projekcie. Nazwa agenta usługi pojawi się pod etykietą Agent usługi, do której należy 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 zasobnika kliknij Napraw. Spowoduje to otwarcie strony uprawnień 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óć na kartę ze stroną importowania/eksportowania w Cloud Firestore.
   7. Powtórz te kroki dla innych zasobników na liście. Pamiętaj, aby wyświetlić wszystkie strony z listy.

7. Kliknij Migracja do agenta usługi Firestore. Jeśli nadal masz zasobniki, które nie przeszły kontroli uprawnień, musisz potwierdzić migrację, klikając Przenieś.

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

Wyświetl stan migracji

Aby sprawdzić stan migracji projektu:

1. W konsoli Google Cloud Platform 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.

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

• Ustaw to ograniczenie w zasadzie organizacji:

  Wymagaj agenta usługi Firestore przy importowaniu i eksportowaniu (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, zobacz Tworzenie zasad organizacji i zarządzanie nimi .

Zastosowanie tego ograniczenia zasady organizacji nie powoduje automatycznego przyznania odpowiednich uprawnień do zasobnika 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. Gdy sprawdzisz i zaktualizujesz uprawnienia zasobników Cloud Storage, możesz ponownie włączyć to ograniczenie.