Importowanie i eksportowanie danych

Możesz korzystać z usługi zarządzanego eksportu i importu, 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 w trybie zgodności z MongoDB można zaimportować do innej bazy danych Cloud Firestore w trybie zgodności z MongoDB. Możesz też wczytać wyeksportowane dane z Cloud Firestore w trybie zgodności z MongoDB do BigQuery.

Na tej stronie opisujemy, jak eksportować i importować dokumenty Cloud Firestore zgodne z MongoDB za pomocą zarządzanej usługi eksportu i importu oraz Cloud Storage. Usługa zarządzanego eksportu i importu Cloud Firestore w trybie zgodności z MongoDB jest dostępna za pomocą narzędzia wiersza poleceń gcloud i interfejsu Cloud Firestore w trybie zgodności z MongoDB API (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 dla projektu w lokalizacji w pobliżu lokalizacji bazy danych Cloud Firestore w trybie zgodności z MongoDB. Nie możesz używać zasobnika „Płatnik żąda” do operacji eksportu i importu.

3. Sprawdź, czy Twoje konto ma niezbędne uprawnienia do korzystania z Cloud Firestore w trybie zgodności z MongoDB 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 w trybie zgodności z MongoDB: Owner, Cloud Datastore Owner lub Cloud Datastore Import Export Admin

   • Role Cloud Storage: Owner lub Storage Admin

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:

• Dostęp do gcloud z konsoli Google Cloud za pomocą 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.

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 istniejącego dokumentu.

• Jeśli dokument w bazie danych nie zostanie zmieniony przez import, pozostanie 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 nazwy plików PARENT_FOLDER_NAME i .overall_export_metadata.

• Importowanie do bazy danych Cloud Firestore w trybie zgodności z MongoDB z eksportu z podzbiorami nie powiedzie się, ponieważ podzbiory nie są obsługiwane w Cloud Firestore w trybie zgodności z MongoDB.

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

• Importowanie do bazy danych Cloud Firestore w trybie zgodności z MongoDB nie może importować danych z przestrzeni nazw innych niż domyślne (Datastore API).

  Importowanie do bazy danych Cloud Firestore zgodnej z MongoDB z plików danych zawierających przestrzenie nazw inne niż domyślne 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 konkretnych kolekcji. Jeśli w bazie danych istnieje już jakiś dokument, zostanie on zastąpiony.

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] \
--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 w określonym momencie nie ma już danych, 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: 2020-09-01T23:59:30.234233Z.
• 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]

Zarządzanie operacjami eksportu i importu

Po rozpoczęciu operacji eksportu lub importu Cloud Firestore w trybie zgodności z MongoDB 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/[DATABASE_ID]/operations/, np.:

projects/my-project/databases/my-database/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 wskaźniki 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 w trybie zgodności z MongoDB 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ępu, 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 eksportu i importu są rozliczane za jednostki odczytu i zapisu według stawek podanych w cenniku Cloud Firestore w trybie zgodności z MongoDB.

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 czasu ich zakończenia. Operacje eksportowania i importowania 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, 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 w trybie zgodności z MongoDB możesz wczytać do BigQuery, ale tylko wtedy, gdy określisz filtr collection-ids. Zobacz Wczytywanie danych z eksportów Cloud Firestore w trybie zgodności z MongoDB.

Podczas wczytywania danych z Cloud Firestore w trybie zgodności z MongoDB do BigQuery typy danych BSON są reprezentowane za pomocą typu danych STRING.

BigQuery limit kolumn

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

Jeśli BigQuery schemat kolekcji przekracza 10 000 kolumn,operacja eksportu Cloud Firestore w trybie zgodności z MongoDB 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 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 tys., operacja eksportu nie wygeneruje schematu BigQuery dla kolekcji i nie będzie można wczytać 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 przez Ciebie kolekcji. Pliki metadanych mają zwykle nazwęALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

Pliki metadanych to bufory protokołu, które możesz dekodować za pomocą protockompilatora protokołu. Możesz na przykład zdekodować plik metadanych, aby określić kolekcje, które zawierają pliki eksportu:

protoc --decode_raw < export0.export_metadata