Importowanie i eksportowanie danych

Możesz korzystać z usługi zarządzanego eksportu i importu, aby przywracać przypadkowo usunięte dane lub eksportować dane do przetwarzania w trybie offline. Możesz wyeksportować wszystkie dokumenty lub tylko określone kolekcje. Możesz też 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 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.

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.

• 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 do bazy danych Cloud Firestore z eksportu z podkolekcjami nie powiedzie się, ponieważ podkolekcje nie są obsługiwane w Cloud Firestore.

• Importowanie do bazy danych Firestore Standard z eksportu z typami BSON nie powiedzie się, ponieważ typy BSON nie są obsługiwane w Firestore Standard.

• Import do bazy danych Cloud Firestore nie może obejmować danych z przestrzeni nazw innych niż domyślne (interfejs API Datastore).

  Importowanie do bazy danych Cloud Firestore z plików danych zawierających niedomyślne przestrzenie nazw jest dozwolone tylko wtedy, gdy operacja eksportu obejmowała filtr --namespace-ids z domyślną przestrzenią nazw. Importowane są tylko dane z domyślnej przestrzeni nazw.

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] \
  --database=[DATABASE]

Importowanie z eksportu z danymi PITR

Aby zaimportować dane PITR, wykonaj te same czynności co w przypadku importowania wszystkich dokumentów lub importowania określonych kolekcji. Jeśli w bazie danych znajduje się już jakiś dokument, zostanie on zastąpiony.

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 kolekcji

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
--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 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 eksportowania PITR obsługuje wszystkie filtry, w tym eksportowanie wszystkich dokumentów i eksportowanie określonych kolekcji.

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

• Określ sygnaturę czasową w formacie RFC 3339. Na przykład: 2020-09-01T23:59:30.234233Z.
• 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]

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/[DATABASE_ID]/operations/, na przykład:

projects/my-project/databases/my-database/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 jednostki odczytu i zapisu według stawek podanych w cenniku Cloud Firestore.

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.

Podczas wczytywania danych Cloud Firestore do BigQuery typy danych BSON są reprezentowane przez typ danych STRING.

Limit kolumn: BigQuery

BigQuery nakłada limit 10 000 kolumn na tabelę. Operacje eksportu Cloud Firestore generują schemat tabeli BigQuery dla każdej kolekcji. W tym schemacie każda unikalna nazwa pola w kolekcji staje się kolumną schematu.

Jeśli schemat BigQuery kolekcji przekracza 10 000 kolumn,operacja eksportu Cloud Firestore próbuje utrzymać się poniżej limitu 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ń do podpól w polach mapy. Jeśli liczba kolumn nadal przekracza 10 000, operacja eksportu nie generuje schematu BigQuery dla 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 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ć kolekcje, które zawierają wyeksportowane pliki:

protoc --decode_raw < export0.export_metadata