Daten exportieren und importieren

Sie können den verwalteten Export- und Importdienst von Firestore 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. Bei Daten, die aus einer Firestore-Datenbank exportiert wurden, besteht die Möglichkeit, sie in eine andere Firestore-Datenbank zu importieren. Sie können auch Firestore-Exporte in BigQuery laden.

Auf dieser Seite wird gezeigt, wie Sie Firestore-Dokumente mithilfe des verwalteten Export- und Importdienstes und von Cloud Storage exportieren bzw. importieren. Der verwaltete Export- und Importdienst für Firestore ist über das gcloud-Befehlszeilentool und über die 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. Die Export- und Importfunktionalität kann nur für Google Cloud-Projekte mit aktivierter Abrechnung verwendet werden.
  2. Erstellen Sie einen Cloud Storage-Bucket für Ihr Projekt an einem Standort in der Nähe des Speicherorts Ihrer Firestore-Datenbank. Sie können für Export- und Importvorgänge keinen Bucket mit der Funktion "Anforderer bezahlt" verwenden.
  3. Sorgen Sie dafür, dass Ihr Konto die erforderlichen Berechtigungen für Cloud Firestore und Cloud Storage hat. Wenn Sie der Projektinhaber sind, enthält Ihr Konto bereits die notwendigen Berechtigungen. Andernfalls gewähren die folgenden Rollen die erforderlichen Berechtigungen für Export- und Importvorgänge und für den Zugriff auf Cloud Storage:

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

Standardberechtigungen für Dienstkonten

Jedes Google Cloud-Projekt erstellt automatisch ein Standarddienstkonto mit dem Namen PROJECT_ID@appspot.gserviceaccount.com. Export- und Importvorgänge verwenden dieses Dienstkonto, um Cloud Storage-Vorgänge zu autorisieren.

Das Standarddienstkonto Ihres Projekts erfordert Zugriff auf den Cloud Storage-Bucket, der in einem Export- oder Importvorgang verwendet wird. Wenn sich Ihr Cloud Storage-Bucket im selben Projekt wie Ihre Firestore-Datenbank befindet, hat das Standarddienstkonto standardmäßig Zugriff auf den Bucket.

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

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

Wenn Sie Ihr App Engine-Standarddienstkonto deaktivieren oder löschen, verliert Ihre App Engine-Anwendung den Zugriff auf Ihre Firestore-Datenbank. Wenn Sie Ihr App Engine-Dienstkonto deaktiviert haben, können Sie es wieder aktivieren. Siehe Dienstkonto aktivieren. Wenn Sie Ihr App Engine-Dienstkonto innerhalb der letzten 30 Tage gelöscht haben, können Sie es wiederherstellen. Weitere Informationen finden Sie unter Dienstkonto wiederherstellen.

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:

Daten exportieren

Bei einem Exportvorgang werden Dokumente Ihrer Datenbank in eine Gruppe von Dateien kopiert, die sich in einem Cloud Storage-Bucket befinden. 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

Google Cloud Console

  1. Gehen Sie zur Seite Firestore-Import/Export in der Google Cloud Console.

    Zur Seite „Import/Export“

  2. Klicken Sie auf Exportieren.

  3. Klicken Sie auf die Option Gesamte Datenbank exportieren.

  4. Geben Sie unter Ziel auswählen den Namen eines Cloud Storage-Buckets ein oder wählen Sie mit der Schaltfläche Suchen einen Bucket aus.

  5. Klicken Sie auf Exportieren.

Die Console kehrt zur Seite Import/Export zurück. Wenn der Vorgang erfolgreich gestartet wird, fügt die Seite der letzten Import- und Exportseite einen Eintrag hinzu. Bei einem Fehler wird auf der Seite eine Fehlermeldung angezeigt.

gcloud

Verwenden Sie den Befehl firestore export, um alle Dokumente Ihrer Datenbank zu exportieren und ersetzen Sie [BUCKET_NAME] durch den Namen Ihres Cloud Storage-Buckets. Fügen Sie das Flag --async hinzu, um zu verhindern, dass das gcloud-Tool auf den Abschluss des Vorgangs wartet.

gcloud firestore export gs://[BUCKET_NAME]

Sie können Ihre Exporte organisieren, indem Sie hinter den Bucket-Namen ein Dateipräfix hinzufügen, z. B. BUCKET_NAME/my-exports-folder/export-name. Wenn Sie kein Dateipräfix angeben, wird vom verwalteten Exportdienst ein Präfix auf Basis des aktuellen Zeitstempels erstellt.

Wenn Sie einen Export gestartet haben, wird der Vorgang durch Schließen des Terminals nicht abgebrochen. Siehe Vorgang abbrechen.

Bestimmte Sammlungen exportieren

Google Cloud Console

  1. Gehen Sie zur Seite Firestore-Import/Export in der Google Cloud Console.

    Zur Seite „Import/Export“

  2. Klicken Sie auf Exportieren.

  3. Klicken Sie auf die Option Eine oder mehrere Sammlungsgruppen exportieren. Wählen Sie im Drop-down-Menü eine oder mehrere Sammlungsgruppen aus.

  4. Geben Sie unter Ziel auswählen den Namen eines Cloud Storage-Buckets ein oder wählen Sie mit der Schaltfläche Suchen einen Bucket aus.

  5. Klicken Sie auf Exportieren.

Die Console kehrt zur Seite Import/Export zurück. Wenn der Vorgang erfolgreich gestartet wird, fügt die Seite der letzten Import- und Exportseite einen Eintrag hinzu. Bei einem Fehler wird auf der Seite eine Fehlermeldung angezeigt.

gcloud

Verwenden Sie das Flag --collection-ids, um bestimmte Sammlungsgruppen zu exportieren. Bei diesem Vorgang werden nur die Sammlungsgruppen mit den angegebenen Sammlungs-IDs exportiert. Eine Sammlungsgruppe enthält alle Sammlungen und untergeordneten Sammlungen (in einem beliebigen Pfad) mit der festgelegten Sammlungs-ID.

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

Daten importieren

Sobald Sie Dateien in Cloud Storage exportiert haben, können Sie Dokumente aus 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.

  • Es werden beim Import 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.

  • Importvorgänge lösen keine Cloud Functions-Funktionen aus. Snapshot-Listener erhalten Aktualisierungen im Zusammenhang mit Importvorgängen.

Alle Dokumente aus einem Export importieren

Google Cloud Console

  1. Gehen Sie zur Seite Firestore-Import/Export in der Google Cloud Console.

    Zur Seite „Import/Export“

  2. Klicken Sie auf Importieren.

  3. Geben Sie im Feld Dateiname den Dateinamen einer .overall_export_metadata-Datei aus einem abgeschlossenen Exportvorgang ein. Sie können die Schaltfläche Durchsuchen verwenden, um die Datei auszuwählen.

  4. Klicken Sie auf Importieren.

Die Console kehrt zur Seite Import/Export zurück. Wenn der Vorgang erfolgreich gestartet wird, fügt die Seite der letzten Import- und Exportseite einen Eintrag hinzu. Bei einem Fehler wird auf der Seite eine Fehlermeldung angezeigt.

gcloud

Verwenden Sie den Befehl firestore import, um Dokumente aus einem vorherigen Exportvorgang zu importieren,

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

wobei [BUCKET_NAME] und [EXPORT_PREFIX] auf den Speicherort Ihrer Exportdateien verweist. Beispiel:

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

Sie können den Speicherort Ihrer Exportdateien im Cloud Storage-Browser in der Google Cloud Console bestätigen:

Cloud Storage-Browser öffnen

Wenn Sie einen Import gestartet haben, wird der Vorgang durch Schließen des Terminals nicht abgebrochen. Siehe Vorgang abbrechen.

Bestimmte Sammlungen importieren

Google Cloud Console

Sie können in der Konsole keine bestimmten Sammlungen auswählen. Verwenden Sie stattdessen gcloud.

gcloud

Verwenden Sie das Flag --collection-ids, um bestimmte Sammlungsgruppen aus einer Gruppe von Exportdateien zu importieren. Bei dem Vorgang werden nur die Sammlungsgruppen mit den angegebenen Sammlungs-IDs importiert. Eine Sammlungsgruppe enthält alle Sammlungen und untergeordneten Sammlungen (in einem beliebigen Pfad) mit der festgelegten Sammlungs-ID.

Nur ein Export bestimmter Sammlungsgruppen unterstützt den Import bestimmter Sammlungsgruppen. Der Import bestimmter Sammlungen aus einem Export aller Dokumente ist nicht möglich.

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

Export- und Importvorgänge verwalten

Nachdem Sie einen Export- oder Importvorgang gestartet haben, weist 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/(default)/operations/, zum Beispiel:

projects/my-project/databases/(default)/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

Google Cloud Console

Eine Liste der letzten Export- und Importvorgänge finden Sie in der Google Cloud Console auf der Seite Firestore-Import/Export.

Zur Seite „Import/Export“

gcloud

Verwenden Sie den Befehl operations list, um alle laufenden und kürzlich abgeschlossenen Export- und Importvorgänge anzeigen zu lassen:

gcloud firestore operations list

Vorgangsstatus prüfen

Google Cloud Console

Sie können den Status eines kürzlichen Export- oder Importvorgangs auf der Seite Firestore-Import/Export der Google Cloud Console einsehen.

Zur Seite „Import/Export“

gcloud

Verwenden Sie den Befehl operations describe, um den Status eines Export- oder Importvorgangs anzeigen zu lassen.

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.

  • 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

Google Cloud Console

Sie können laufende Export- oder Importvorgänge auf der Seite Firestore-Import/Export der Google Cloud Console abbrechen.

Zur Seite „Import/Export“

In der Tabelle Aktuelle Importe und Exporte enthalten aktuell ausgeführte Vorgänge die Schaltfläche Abbrechen in der Spalte Abgeschlossen. Klicken Sie auf die Schaltfläche Abbrechen, um den Vorgang zu beenden. Die Schaltfläche ändert sich in eine Abbrechen- und, sobald der Vorgang komplett ist, in eine Storniert-Nachricht.

gcloud

Verwenden Sie den Befehl operations cancel, um einen laufenden Vorgang zu stoppen:

gcloud firestore operations cancel [OPERATION_NAME]

Durch das Abbrechen eines laufenden Vorgangs wird der Vorgang nicht rückgängig gemacht. Bei einem abgebrochenen Exportvorgang werden die bereits in Cloud Storage exportierten Dokumente beibehalten. Bei einem abgebrochenen Importvorgang werden die bereits an der Datenbank vorgenommenen Aktualisierungen beibehalten. 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

Damit Sie den verwalteten Export- und Importdienst verwenden können, müssen Sie die Abrechnung für Ihr Google Cloud-Projekt aktivieren. Für Export- und Importvorgänge werden die Lese- und Schreibvorgänge von Dokumenten zu den Preisen für Firestore berechnet.

Die Kosten für Export- und Importvorgänge werden nicht auf das Ausgabenlimit angerechnet. Export- oder Importvorgänge werden erst nach Abschluss auf das Google Cloud-Budget angerechnet. Die während eines Export- oder Importvorgangs ausgeführten Lese- und Schreibvorgänge werden nach Abschluss des Vorgangs auf Ihr tägliches Kontingent angerechnet. Export- und Importvorgänge wirken sich nicht auf die im Abschnitt "Nutzung" der Konsole angezeigte Nutzung aus.

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:

Über das Filtermenü auf das Label "goog-firestoremanaged" zugreifen.

Nach BigQuery exportieren

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

BigQuery-Spaltenlimit

In BigQuery gilt ein Limit von 10.000 Spalten pro Tabelle. Firestore-Exportvorgänge generieren für jede Sammlungsgruppe ein BigQuery-Tabellenschema. In diesem Schema dient jeder eindeutige Feldname innerhalb einer Sammlungsgruppe als Schemaspalte.

Wenn das BigQuery-Schema einer Sammlungsgruppe mehr als 10.000 Spalten umfasst, wird beim Firestore-Exportvorgang versucht, die Spaltenbeschränkung zu beachten. Dazu werden die Map-Felder in Form von Byte behandelt. Wenn durch diese Umwandlung die Anzahl der Spalten 10.000 nicht übersteigt, können Sie die Daten in BigQuery laden, aber nicht die Unterfelder innerhalb der Map-Felder abfragen. Wenn die Anzahl der Spalten immer noch über 10.000 beträgt, erzeugt der Exportvorgang kein BigQuery-Schema für die Sammlungsgruppe und die Daten können nicht in BigQuery geladen werden.

Exportformat und Metadatendateien

Die Ausgabe eines verwalteten Exports verwendet das LevelDB-Logformat.

Metadatendateien

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

Die Metadatendateien sind Protokollpuffer und können mit dem Protokollcompiler protoc decodiert werden. Sie können beispielsweise eine Metadatendatei decodieren, um die Sammlungsgruppen zu bestimmen, die die Exportdateien enthalten:

protoc --decode_raw < export0.export_metadata