Daten importieren und exportieren

Sie können den verwalteten Export- und Importdienst dazu verwenden, versehentlich gelöschte Daten wiederherzustellen und Daten für die Offlineverarbeitung zu exportieren. Es lassen sich alle Dokumente oder nur bestimmte Sammlungen exportieren. Ebenso können Sie alle Daten aus einem Export oder nur bestimmte Sammlungen daraus importieren. Daten, die aus einer Cloud Firestore-Datenbank exportiert wurden, können in eine andere Cloud Firestore-Datenbank importiert werden. Sie können auch Cloud Firestore-Exporte in BigQuery laden.

Auf dieser Seite wird beschrieben, wie Sie Cloud Firestore-Dokumente mit dem verwalteten Export- und Importdienst und Cloud Storage exportieren und importieren. Der verwaltete Export- und Importdienst von Cloud Firestore ist über das gcloud-Befehlszeilentool und die Cloud Firestore API (REST, RPC) verfügbar.

Hinweis

Bevor Sie den verwalteten Export- und Importdienst verwenden können, müssen Sie die folgenden Schritte ausführen:

1. Aktivieren Sie die Abrechnung für Ihr Google Cloud-Projekt. Nur Google Cloud-Projekte mit aktivierter Abrechnung können die Export- und Importfunktion verwenden.
2. Erstellen Sie einen Cloud Storage-Bucket für Ihr Projekt an einem Standort in der Nähe des Standorts Ihrer Cloud Firestore-Datenbank. Sie können einen Bucket mit der Funktion „Anforderer bezahlt“ oder einen Rapid-Bucket nicht für Export- und Importvorgänge verwenden.

3. Ihr Konto muss die erforderlichen Berechtigungen für Cloud Firestore und Cloud Storage haben. Wenn Sie der Projektinhaber sind, hat Ihr Konto die erforderlichen Berechtigungen. Andernfalls gewähren die folgenden Rollen die erforderlichen Berechtigungen für Export- und Importvorgänge sowie für den Zugriff auf Cloud Storage:

   • Cloud Firestore-Rollen: Owner, Cloud Datastore Owner oder Cloud Datastore Import Export Admin

   • Cloud Storage-Rollen: Owner oder Storage Admin

Berechtigungen des Dienst-Agents

Bei Export- und Importvorgängen wird ein Cloud Firestore-Dienst-Agent verwendet, um Cloud Storage-Vorgänge zu autorisieren. Der Dienst-Agent Cloud Firestore verwendet die folgende Namenskonvention:

Cloud Firestore-Dienst-Agent

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

Weitere Informationen zu Dienst-Agents finden Sie unter Dienst-Agents.

Der Dienst-Agent Cloud Firestore benötigt Zugriff auf den Bucket Cloud Storage, der für einen Export- oder Importvorgang verwendet wird. Wenn sich Ihr Cloud Storage-Bucket im selben Projekt wie Ihre Cloud Firestore-Datenbank befindet, kann der Cloud Firestore-Dienst-Agent standardmäßig auf den Bucket zugreifen.

Wenn sich der Cloud Storage-Bucket in einem anderen Projekt befindet, müssen Sie dem Cloud Firestore-Dienst-Agent Zugriff auf den Cloud Storage-Bucket gewähren.

Dem Dienst-Agent Rollen zuweisen

Sie können das gsutil-Befehlszeilentool verwenden, um eine der folgenden Rollen zuzuweisen. Führen Sie beispielsweise den folgenden Befehl aus, um dem Dienst-Agent Cloud Firestore die Rolle „Storage-Administrator“ zuzuweisen:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Ersetzen Sie PROJECT_NUMBER durch Ihre Projektnummer, die zur Benennung Ihres Cloud Firestore-Dienst-Agents verwendet wird. Informationen zum Aufrufen des Dienst-Agent-Namens finden Sie unter Dienst-Agent-Namen aufrufen.

Alternativ können Sie diese Rolle über die Google Cloud Console zuweisen.

Name des Dienst-Agents ansehen

Sie können das Konto, das Ihre Import- und Exportvorgänge zum Autorisieren von Anfragen verwenden, auf der Seite Import/Export in der Google Cloud Console aufrufen. Sie können auch sehen, ob Ihre Datenbank den Dienst-Agent Cloud Firestore oder das Legacy-Dienstkonto App Engine verwendet.

1. Sehen Sie sich das Autorisierungskonto neben dem Label Import-/Exportjobs ausführen als an.

Der Dienst-Agent benötigt die Rolle Storage Admin für den Bucket Cloud Storage, der für den Export- oder Importvorgang verwendet werden soll.

gcloud für das Projekt einrichten

Sie können Import- und Exportvorgänge über die Google Cloud Console oder das gcloud-Befehlszeilentool initiieren. Richten Sie das Befehlszeilentool ein, um gcloud zu verwenden, und stellen Sie mit einer der folgenden Methoden eine Verbindung zu Ihrem Projekt her:

• Greifen Sie über die Google Cloud-Konsole mit Cloud Shell auf gcloud zu.

  Cloud Shell starten

  Achten Sie darauf, dass gcloud für das richtige Projekt konfiguriert ist:

  gcloud config set project [PROJECT_ID]
  

• Installieren und initialisieren Sie das Google Cloud SDK.

Daten importieren

Sobald Sie Exportdateien in Cloud Storage haben, können Sie Dokumente in diesen Dateien wieder in Ihr Projekt oder in ein anderes Projekt importieren. Beachten Sie die folgenden Punkte zu Importvorgängen:

• Beim Importieren von Daten werden die erforderlichen Indexe mit den aktuellen Indexdefinitionen der Datenbank aktualisiert. Ein Export enthält keine Indexdefinitionen.

• Beim Importieren werden keine neuen Dokument-IDs zugewiesen. Für den Import werden die IDs verwendet, die zum Zeitpunkt des Exports erfasst wurden. Die ID eines Dokuments wird beim Import reserviert, um ID-Kollisionen zu vermeiden. Wenn ein Dokument mit derselben ID bereits vorhanden ist, wird das vorhandene Dokument durch den Import überschrieben.

• Wenn ein Dokument in Ihrer Datenbank nicht von einem Import betroffen ist, bleibt es nach dem Import in Ihrer Datenbank bestehen.

• Der Dateiname .overall_export_metadata muss mit dem Namen des übergeordneten Ordners übereinstimmen:

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

  Wenn Sie die Ausgabedateien eines Exports verschieben oder kopieren, behalten Sie die Dateinamen PARENT_FOLDER_NAME und .overall_export_metadata bei.

• Ein Import in eine Cloud Firestore-Datenbank aus einem Export mit Untersammlungen schlägt fehl, da Untersammlungen in Cloud Firestore nicht unterstützt werden.

• Der Import in eine Firestore Standard-Datenbank aus einem Export mit BSON-Typen schlägt fehl, da BSON-Typen in Firestore Standard nicht unterstützt werden.

• Bei einem Import in eine Cloud Firestore-Datenbank können keine Daten aus Nicht-Standard-Namespaces (Datastore API) importiert werden.

  Ein Import in eine Cloud Firestore-Datenbank aus Datendateien, die nicht standardmäßige Namespaces enthalten, ist nur zulässig, wenn der Exportvorgang einen --namespace-ids-Filter mit dem Standard-Namespace enthielt. Es werden nur Daten aus dem Standard-Namespace importiert.

Alle Dokumente aus einem Export importieren

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Bestimmte Sammlungen importieren

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

Aus einem Export mit PITR-Daten importieren

Führen Sie die gleichen Schritte wie unter Alle Dokumente importieren oder Bestimmte Sammlungen importieren aus, um PITR-Daten zu importieren. Wenn ein Dokument bereits in Ihrer Datenbank vorhanden ist, wird es überschrieben.

Daten exportieren

Bei einem Exportvorgang werden Dokumente in Ihrer Datenbank in eine Reihe von Dateien in einem Cloud Storage-Bucket kopiert. Beachten Sie, dass ein Export kein exakter Datenbank-Snapshot ist, der zum Startzeitpunkt des Exports aufgenommen wurde. Ein Export kann Änderungen enthalten, die während der Ausführung des Vorgangs vorgenommen wurden.

Alle Dokumente exportieren

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Bestimmte Sammlungen exportieren

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'

Von einem PITR-Zeitstempel exportieren

Sie können Ihre Datenbank aus PITR-Daten nach Cloud Storage exportieren. Sie können PITR-Daten exportieren, deren Zeitstempel ein Zeitstempel mit ganzen Minuten innerhalb der letzten sieben Tage ist, aber nicht vor dem earliestVersionTime. Wenn am angegebenen Zeitstempel keine Daten mehr vorhanden sind, schlägt der Exportvorgang fehl.

Der PITR-Exportvorgang unterstützt alle Filter, einschließlich des Exports aller Dokumente und des Exports bestimmter Sammlungen.

Beachten Sie vor dem Exportieren von PITR-Daten die folgenden Punkte:

• Geben Sie den Zeitstempel im RFC 3339-Format an. Beispiel: 2020-09-01T23:59:30.234233Z.
• Der angegebene Zeitstempel muss ein Zeitstempel mit einer ganzen Minute innerhalb der letzten sieben Tage sein, aber nicht vor dem earliestVersionTime. Wenn am angegebenen Zeitstempel keine Daten mehr vorhanden sind, wird ein Fehler generiert.
• Für einen fehlgeschlagenen PITR-Export fallen keine Kosten an.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Export- und Importvorgänge verwalten

Nachdem Sie einen Export- oder Importvorgang gestartet haben, weist Cloud Firestore dem Vorgang einen eindeutigen Namen zu. Sie können mit diesem Namen den Vorgang löschen, abbrechen oder seinen Status prüfen.

Vorgangsnamen haben das Präfix projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/, zum Beispiel:

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Wenn Sie für die Befehle describe, cancel und delete einen Vorgangsnamen angeben, können Sie das Präfix weglassen.

Alle Export- und Importvorgänge auflisten

gcloud firestore operations list

Vorgangsstatus prüfen

gcloud firestore operations describe [OPERATION_NAME]

Fertigstellungszeit schätzen

Eine Anfrage für den Status eines Vorgangs mit langer Ausführungszeit liefert die Messwerte workEstimated und workCompleted. Beide Messwerte werden als Anzahl der Byte und als Anzahl der Entitäten zurückgegeben:

• workEstimated weist die geschätzte Gesamtzahl der Byte und Dokumente aus, die ein Vorgang verarbeitet. Cloud Firestore lässt diesen Messwert möglicherweise weg, wenn keine Schätzung möglich ist.

• workCompleted weist die Anzahl der bisher verarbeiteten Byte und Dokumente aus. Nachdem der Vorgang abgeschlossen ist, zeigt der Wert die Gesamtanzahl der tatsächlich verarbeiteten Byte und Dokumente an, die möglicherweise größer als der Wert von workEstimated ist.

Teilen Sie workCompleted durch workEstimated, um eine grobe Schätzung des Fortschritts zu erhalten. Diese Schätzung ist möglicherweise ungenau, da sie von der verzögerten Statistikerfassung abhängt.

Vorgang abbrechen

gcloud firestore operations cancel [OPERATION_NAME]

Durch das Abbrechen eines laufenden Vorgangs wird der Vorgang nicht rückgängig gemacht. Bei einem abgebrochenen Exportvorgang verbleiben bereits exportierte Dokumente in Cloud Storage. Bei einem abgebrochenen Importvorgang bleiben bereits vorgenommene Aktualisierungen in Ihrer Datenbank erhalten. Sie können einen unvollständigen Export nicht importieren.

Vorgang löschen

Verwenden Sie den Befehl gcloud firestore operations delete, um einen Vorgang aus der Liste der letzten Vorgänge zu entfernen. Mit diesem Befehl werden keine Exportdateien aus Cloud Storage gelöscht.

gcloud firestore operations delete [OPERATION_NAME]

Abrechnung und Preise für Export- und Importvorgänge

Sie müssen die Abrechnung für Ihr Google Cloud-Projekt aktivieren, bevor Sie den verwalteten Export- und Importdienst verwenden können.

Export- und Importvorgänge werden für Lese- und Schreibvorgänge zu den unter Cloud Firestore-Preise aufgeführten Preisen in Rechnung gestellt.

In Cloud Storage gespeicherte Ausgabedateien werden auf Ihre Cloud Storage-Datenspeicherkosten angerechnet.

Export- oder Importvorgänge lösen erst nach Abschluss Ihre Google Cloud-Budgetbenachrichtigungen aus. Export- und Importvorgänge wirken sich nicht auf die Nutzung aus, die im Abschnitt „Nutzung“ der Console angezeigt wird.

Preise für Export und Import aufrufen

Bei Export- und Importvorgängen wird das goog-firestoremanaged:exportimport-Label auf in Rechnung gestellte Vorgänge angewendet. Auf der Seite der Cloud Billing-Berichte können Sie über dieses Label Kosten für Import- und Exportvorgänge aufrufen:

Nach BigQuery exportieren

Sie können Daten aus einem Cloud Firestore-Export in BigQuery laden, aber nur, wenn Sie einen collection-ids-Filter angegeben haben. Weitere Informationen finden Sie unter Daten aus Cloud Firestore-Exporten laden.

Beim Laden von Cloud Firestore-Daten in BigQuery werden BSON-Datentypen mit dem Datentyp STRING dargestellt.

Spaltenlimit: BigQuery

BigQuery legt ein Limit von 10.000 Spalten pro Tabelle fest. Cloud Firestore-Exportvorgänge generieren für jede Sammlung ein BigQuery-Tabellenschema. In diesem Schema wird jeder eindeutige Feldname innerhalb einer Sammlung zu einer Schemaspalte.

Wenn das BigQuery-Schema einer Sammlung mehr als 10.000 Spalten umfasst, versucht der Cloud Firestore-Exportvorgang, die Spaltenbeschränkung einzuhalten, indem Kartenfelder als Byte behandelt werden. Wenn die Anzahl der Spalten durch diese Konvertierung unter 10.000 sinkt, können Sie die Daten in BigQuery laden, aber die Unterfelder in den Kartenfeldern nicht abfragen. Wenn die Anzahl der Spalten immer noch 10.000 überschreitet, wird beim Exportvorgang kein BigQuery-Schema für die Sammlung generiert und Sie können die Daten nicht in BigQuery laden.

Exportformat und Metadatendateien

Die Ausgabe eines verwalteten Exports verwendet das LevelDB-Logformat.

Metadatendateien

Bei einem Exportvorgang wird für jede von Ihnen angegebene Sammlung eine Metadatendatei erstellt. Metadatendateien heißen in der Regel ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

Die Metadatendateien sind Protokollzwischenspeicher und können mit dem protoc-Protokollcompiler decodiert werden. Sie können beispielsweise eine Metadatendatei decodieren, um die Sammlungen zu ermitteln, die die Exportdateien enthalten:

protoc --decode_raw < export0.export_metadata