Daten exportieren und importieren

Sie können den von Cloud Firestore verwalteten Export- und Importdienst verwenden, um versehentlich gelöschte Daten wiederherzustellen und Daten für die Offline-Verarbeitung zu exportieren. Sie können alle Dokumente oder nur bestimmte Sammlungen exportieren. Ebenso können Sie alle Daten aus einem Export oder nur bestimmte Sammlungen importieren. Aus einer Cloud Firestore-Datenbank exportierte Daten können in eine andere Cloud Firestore-Datenbank importiert werden. Sie können Cloud Firestore-Exporte auch 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 von Cloud Firestore verwaltete Export- und Importdienst ist über das gcloud Befehlszeilentool und die Cloud Firestore-API ( REST , RPC ) verfügbar.

Bevor Sie beginnen

Bevor Sie den verwalteten Export- und Importdienst verwenden können, müssen Sie die folgenden Aufgaben 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 nutzen.
  2. Erstellen Sie einen Cloud Storage-Bucket für Ihr Projekt an einem Standort in der Nähe Ihres Cloud Firestore-Datenbankstandorts . Sie können einen Bucket „Anforderer zahlt“ nicht für Export- und Importvorgänge verwenden.
  3. Stellen Sie sicher, dass Ihr Konto über die erforderlichen Berechtigungen für Cloud Firestore und Cloud Storage verfügt. Wenn Sie der Projekteigentümer sind, verfügt Ihr Konto über die erforderlichen Berechtigungen. Ansonsten gewähren die folgenden Rollen die notwendigen 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-Speicherrollen: Owner oder Storage Admin

Berechtigungen des Service-Agenten

Export- und Importvorgänge verwenden einen Cloud Firestore-Dienstagenten, um Cloud Storage-Vorgänge zu autorisieren. Der Cloud Firestore-Dienstagent verwendet die folgende Namenskonvention:

Cloud Firestore-Dienstagent
service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

Weitere Informationen zu Serviceagenten finden Sie unter Serviceagenten .

Der Cloud Firestore-Dienstagent benötigt 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 Cloud Firestore-Datenbank befindet, kann der Cloud Firestore-Dienstagent standardmäßig auf den Bucket zugreifen .

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

Weisen Sie dem Serviceagenten Rollen zu

Sie können das Befehlszeilentool gsutil verwenden, um eine der folgenden Rollen zuzuweisen. Um beispielsweise dem Cloud Firestore-Dienstagenten die Rolle „Speicheradministrator“ zuzuweisen, führen Sie Folgendes aus:

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-Dienstagenten verwendet wird. Informationen zum Anzeigen des Service-Agent-Namens finden Sie unter Service-Agent-Namen anzeigen .

Alternativ können Sie diese Rolle auch über die GCP Console zuweisen .

Name des Serviceagenten anzeigen

Sie können das Konto, das Ihre Import- und Exportvorgänge zum Autorisieren von Anforderungen verwenden, auf der Seite „Import/Export“ in der Google Cloud Platform Console anzeigen. Sie können auch anzeigen, ob Ihre Datenbank den Cloud Firestore-Dienstagenten oder das alte App Engine-Dienstkonto verwendet.

  1. Sehen Sie sich das Autorisierungskonto neben der Bezeichnung „Import/Export-Jobs ausführen als“ an.

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

Richten Sie gcloud für Ihr Projekt ein

Sie können Import- und Exportvorgänge über die Google Cloud Platform Console oder das gcloud Befehlszeilentool initiieren. Um gcloud zu verwenden, richten Sie das Befehlszeilentool ein und stellen Sie auf eine der folgenden Arten eine Verbindung zu Ihrem Projekt her:

Daten exportieren

Ein Exportvorgang kopiert Dokumente in Ihrer Datenbank in eine Reihe von Dateien in einem Cloud Storage-Bucket. Beachten Sie, dass es sich bei einem Export nicht um einen exakten Datenbank-Snapshot handelt, der zum Startzeitpunkt des Exports erstellt wird. Ein Export kann Änderungen umfassen, die während der Ausführung des Vorgangs vorgenommen wurden.

Alle Dokumente exportieren

Google Cloud Console

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

  4. Klicken Sie auf Exportieren .

  5. Klicken Sie auf die Option Gesamte Datenbank exportieren .

  6. Geben Sie unter „Ziel auswählen“ den Namen eines Cloud Storage-Buckets ein oder verwenden Sie die Schaltfläche „Durchsuchen“ , um einen Bucket auszuwählen.

  7. Klicken Sie auf Exportieren .

Die Konsole kehrt zur Import/Export- Seite zurück. Wenn der Vorgang erfolgreich gestartet wird, fügt die Seite einen Eintrag zur Seite „Letzte Importe und Exporte“ hinzu. Bei einem Fehler wird auf der Seite eine Fehlermeldung angezeigt.

gcloud

Verwenden Sie den firestore export , um alle Dokumente in Ihrer Datenbank zu exportieren. Ersetzen Sie dabei [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] \
  --database=[DATABASE]

Ersetzen Sie Folgendes:

  • BUCKET_NAME : Organisieren Sie Ihre Exporte, indem Sie nach dem Bucket-Namen ein Dateipräfix hinzufügen, zum Beispiel BUCKET_NAME/my-exports-folder/export-name . Wenn Sie kein Dateipräfix angeben, erstellt der verwaltete Exportdienst eines basierend auf dem aktuellen Zeitstempel.

  • DATABASE : Name der Datenbank, aus der Sie die Dokumente exportieren möchten. Verwenden Sie für die Standarddatenbank --database='(default)' .

Sobald Sie einen Exportvorgang starten, wird der Vorgang durch das Schließen des Terminals nicht abgebrochen, siehe Vorgang abbrechen .

Exportieren Sie bestimmte Sammlungen

Google Cloud Console

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

  4. Klicken Sie auf Exportieren .

  5. Klicken Sie auf die Option Eine oder mehrere Sammlungsgruppen exportieren . Verwenden Sie das Dropdown-Menü, um eine oder mehrere Sammlungsgruppen auszuwählen.

  6. Geben Sie unter „Ziel auswählen“ den Namen eines Cloud Storage-Buckets ein oder verwenden Sie die Schaltfläche „Durchsuchen“ , um einen Bucket auszuwählen.

  7. Klicken Sie auf Exportieren .

Die Konsole kehrt zur Import/Export- Seite zurück. Wenn der Vorgang erfolgreich gestartet wird, fügt die Seite einen Eintrag zur Seite „Letzte Importe und Exporte“ hinzu. Bei einem Fehler wird auf der Seite eine Fehlermeldung angezeigt.

gcloud

Um bestimmte Sammlungsgruppen zu exportieren, verwenden Sie das Flag --collection-ids . Der Vorgang exportiert nur die Sammlungsgruppen mit den angegebenen Sammlungs-IDs. Die Sammlungsgruppe umfasst alle Sammlungen und Untersammlungen (in jedem Pfad) mit der angegebenen Sammlungs-ID.

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

Sie können beispielsweise eine restaurants in der foo Datenbank so entwerfen, dass sie mehrere Untersammlungen enthält, z. B. ratings , reviews “ oder outlets . Um eine bestimmte Sammlung restaurants und reviews zu exportieren, sieht Ihr Befehl wie folgt aus:

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Export von einem PITR-Zeitstempel

Mit dem Befehl gcloud firestore export können Sie Ihre Datenbank aus PITR-Daten in Cloud Storage exportieren. Sie können PITR-Daten exportieren, bei denen der Zeitstempel ein ganzer Minutenzeitstempel innerhalb der letzten sieben Tage ist, jedoch nicht früher als die earliestVersionTime . Wenn zum 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.

  1. Exportieren Sie die Datenbank und geben Sie dabei den snapshot-time Parameter auf den gewünschten Wiederherstellungszeitstempel an.

    gcloud

    Führen Sie den folgenden Befehl aus, um die Datenbank in Ihren Bucket zu exportieren.

    gcloud firestore export gs://[BUCKET_NAME_PATH] \
        --snapshot-time=[PITR_TIMESTAMP] \
        --collection-ids=[COLLECTION_IDS] \
        --namespace-ids=[NAMESPACE_IDS]
    

    Wo,

    • PITR_TIMESTAMP – ein PITR-Zeitstempel mit Minutengranularität, zum Beispiel 2023-05-26T10:20:00.00Z .

    Beachten Sie die folgenden Punkte, bevor Sie PITR-Daten exportieren:

    • Geben Sie den Zeitstempel im RFC 3339-Format an. Beispiel: 2020-09-01T23:59:30.234233Z .
    • Stellen Sie sicher, dass der von Ihnen angegebene Zeitstempel ein ganzer Minutenzeitstempel der letzten sieben Tage ist, jedoch nicht früher als die earliestVersionTime . Wenn zum angegebenen Zeitstempel keine Daten mehr vorhanden sind, wird ein Fehler generiert.
    • Für einen fehlgeschlagenen PITR-Export werden Ihnen keine Kosten berechnet.

Daten importieren

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

  • Wenn Sie Daten importieren, werden die erforderlichen Indizes mithilfe der aktuellen Indexdefinitionen Ihrer Datenbank aktualisiert. Ein Export enthält keine Indexdefinitionen.

  • Durch Importe werden keine neuen Dokument-IDs zugewiesen. Für Importe werden die zum Zeitpunkt des Exports erfassten IDs verwendet. Während ein Dokument importiert wird, wird seine ID reserviert, um ID-Kollisionen zu verhindern. Wenn bereits ein Dokument mit derselben ID vorhanden ist, überschreibt der Import das vorhandene Dokument.

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

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

  • Der Name der .overall_export_metadata Datei 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 den gleichen Namen für PARENT_FOLDER_NAME und .overall_export_metadata bei.

Importieren Sie alle Dokumente aus einem Export

Google Cloud Console

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

  4. Klicken Sie auf Importieren .

  5. 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.

  6. Klicken Sie auf Importieren .

Die Konsole kehrt zur Import/Export- Seite zurück. Wenn der Vorgang erfolgreich gestartet wird, fügt die Seite einen Eintrag zur Seite „Letzte Importe und Exporte“ hinzu. Bei einem Fehler wird auf der Seite eine Fehlermeldung angezeigt.

gcloud

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

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

Ersetzen Sie Folgendes:

  • BUCKET_NAME/EXPORT_PREFIX : Speicherort Ihrer Exportdateien.

  • DATABASE : Name der Datenbank. Verwenden Sie für die Standarddatenbank --database='(default)' .

Zum Beispiel:

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

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

Öffnen Sie den Cloud Storage-Browser

Sobald Sie einen Importvorgang starten, wird der Vorgang durch das Schließen des Terminals nicht abgebrochen, siehe Vorgang abbrechen .

Importieren Sie bestimmte Sammlungen

Google Cloud Console

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

gcloud

Um bestimmte Sammlungsgruppen aus einer Reihe von Exportdateien zu importieren, verwenden Sie das Flag --collection-ids . Der Vorgang importiert nur die Sammlungsgruppen mit den angegebenen Sammlungs-IDs. Die Sammlungsgruppe umfasst alle Sammlungen und Untersammlungen (in jedem Pfad) mit der angegebenen Sammlungs-ID. Geben Sie den Datenbanknamen mit dem Flag --database an. Verwenden Sie für die Standarddatenbank --database='(default)' .

Nur ein Export bestimmter Sammlungsgruppen unterstützt einen Import bestimmter Sammlungsgruppen. Sie können bestimmte Sammlungen nicht aus einem Export aller Dokumente importieren.

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

Importieren Sie einen PITR-Export

Führen Sie die Schritte unter „Alle Dokumente importieren“ aus, um Ihre exportierte Datenbank zu importieren. Wenn in Ihrer Datenbank bereits ein Dokument vorhanden ist, wird es überschrieben.

Verwalten von Export- und Importvorgängen

Nachdem Sie einen Export- oder Importvorgang gestartet haben, weist Cloud Firestore dem Vorgang einen eindeutigen Namen zu. Sie können den Vorgangsnamen verwenden, um den Vorgang zu löschen, abzubrechen oder seinen Status zu überprüfen.

Den Operationsnamen wird das Präfix projects/[PROJECT_ID]/databases/(default)/operations/ vorangestellt, zum Beispiel:

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Sie können das Präfix jedoch weglassen, wenn Sie einen Operationsnamen für die Befehle describe , cancel “ und „ delete angeben.

Listen Sie alle Export- und Importvorgänge auf

Google Cloud Console

Sie können eine Liste der letzten Export- und Importvorgänge auf der Seite „Import/Export“ der Google Cloud Platform Console anzeigen.

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

gcloud

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

gcloud firestore operations list

Überprüfen Sie den Betriebsstatus

Google Cloud Console

Sie können den Status eines kürzlich durchgeführten Export- oder Importvorgangs auf der Seite „Import/Export“ der Google Cloud Platform Console anzeigen.

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

gcloud

Verwenden Sie den Befehl operations describe , um den Status eines Export- oder Importvorgangs anzuzeigen.

gcloud firestore operations describe [OPERATION_NAME]

Schätzen Sie die Fertigstellungszeit

Eine Anfrage nach dem Status eines lang andauernden Vorgangs gibt die Metriken workEstimated und workCompleted zurück. Jede dieser Metriken wird sowohl in der Anzahl der Bytes als auch in der Anzahl der Entitäten zurückgegeben:

  • workEstimated zeigt die geschätzte Gesamtzahl der Bytes und Dokumente an, die ein Vorgang verarbeiten wird. Cloud Firestore lässt diese Metrik möglicherweise weg, wenn keine Schätzung möglich ist.

  • workCompleted zeigt die Anzahl der bisher verarbeiteten Bytes und Dokumente an. Nach Abschluss des Vorgangs zeigt der Wert die Gesamtzahl der tatsächlich verarbeiteten Bytes und Dokumente an, die möglicherweise größer als der Wert von workEstimated ist.

Für eine grobe Fortschrittsschätzung teilen Sie workCompleted durch workEstimated auf. Diese Schätzung ist möglicherweise ungenau, da sie von einer verzögerten Statistikerfassung abhängt.

Brechen Sie einen Vorgang ab

Google Cloud Console

Sie können einen laufenden Export- oder Importvorgang auf der Seite „Import/Export“ der Google Cloud Platform Console abbrechen.

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

In der Tabelle „Letzte Importe und Exporte“ enthalten aktuell ausgeführte Vorgänge in der Spalte „Abgeschlossen“ eine Schaltfläche „Abbrechen“ . Klicken Sie auf die Schaltfläche „Abbrechen“ , um den Vorgang abzubrechen. Die Schaltfläche ändert sich in die Meldung „Abbrechen“ und dann in „Abgebrochen“ , wenn der Vorgang vollständig beendet wird.

gcloud

Verwenden Sie den Befehl operations cancel , um eine laufende Operation zu stoppen:

gcloud firestore operations cancel [OPERATION_NAME]

Das Abbrechen eines laufenden Vorgangs macht den Vorgang nicht rückgängig. Bei einem abgebrochenen Exportvorgang bleiben die Dokumente bereits im Cloud-Speicher exportiert, und bei einem abgebrochenen Importvorgang bleiben bereits an Ihrer Datenbank vorgenommene Aktualisierungen erhalten. Sie können einen teilweise abgeschlossenen Export nicht importieren.

Löschen Sie einen Vorgang

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

gcloud firestore operations delete [OPERATION_NAME]

Abrechnung und Preisgestaltung 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 nutzen.

Export- und Importvorgänge werden für das Lesen und Schreiben von Dokumenten zu den in den Cloud Firestore-Preisen aufgeführten Tarifen berechnet. Für Exportvorgänge ist ein Lesevorgang pro exportiertem Dokument erforderlich. Bei Importvorgängen ist ein Schreibvorgang pro importiertem Dokument erforderlich.

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

Die Kosten für Export- und Importvorgänge werden nicht auf Ihr Ausgabenlimit angerechnet. Export- oder Importvorgänge lösen Ihre Google Cloud-Budgetbenachrichtigungen erst nach Abschluss aus. Ebenso werden Lese- und Schreibvorgänge, die während eines Export- oder Importvorgangs durchgeführt werden, nach Abschluss des Vorgangs auf Ihr Tageskontingent angewendet. Export- und Importvorgänge haben keinen Einfluss auf die im Nutzungsabschnitt der Konsole angezeigte Nutzung.

Export- und Importkosten anzeigen

Export- und Importvorgänge wenden die Bezeichnung goog-firestoremanaged:exportimport auf abgerechnete Vorgänge an. Auf der Seite „Cloud Billing-Berichte“ können Sie dieses Label verwenden, um Kosten im Zusammenhang mit Import- und Exportvorgängen anzuzeigen:

Greifen Sie über das Filtermenü auf das Label „goog-firestoremanaged“ zu.

Nach BigQuery exportieren

Sie können Daten aus einem Cloud Firestore-Export in BigQuery laden, jedoch nur, wenn Sie einen collection-ids Filter angegeben haben. Siehe Laden von Daten aus Cloud Firestore-Exporten .

BigQuery-Spaltenlimit

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

Wenn das BigQuery-Schema einer Sammlungsgruppe 10.000 Spalten überschreitet, versucht der Cloud Firestore-Exportvorgang, unter der Spaltenbeschränkung zu bleiben, indem Kartenfelder als Bytes behandelt werden. Wenn durch diese Konvertierung die Anzahl der Spalten unter 10.000 sinkt, können Sie die Daten in BigQuery laden, aber Sie können die Unterfelder innerhalb der Kartenfelder nicht abfragen. Wenn die Anzahl der Spalten immer noch 10.000 überschreitet, generiert der Exportvorgang kein BigQuery-Schema für die Sammlungsgruppe und Sie können deren Daten nicht in BigQuery laden.

Exportformat- und Metadatendateien

Die Ausgabe eines verwalteten Exports verwendet das LevelDB-Protokollformat .

Metadatendateien

Ein Exportvorgang erstellt eine Metadatendatei für jede von Ihnen angegebene Sammlungsgruppe. Metadatendateien heißen normalerweise ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata .

Die Metadatendateien sind Protokollpuffer und können mit dem protoc -Compiler entschlüsselt werden. Sie können beispielsweise eine Metadatendatei dekodieren, um die Sammlungsgruppen zu bestimmen, die die Exportdateien enthalten:

protoc --decode_raw < export0.export_metadata

Migration von Service-Agenten

Cloud Firestore verwendet einen Cloud Firestore-Dienstagenten, um Import- und Exportvorgänge zu autorisieren, anstatt das App Engine-Dienstkonto zu verwenden. Der Dienstagent und das Dienstkonto verwenden die folgenden Namenskonventionen:

Cloud Firestore-Dienstagent
service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

Cloud Firestore verwendete zuvor das App Engine-Standarddienstkonto anstelle des Cloud Firestore-Dienstagenten. Wenn Ihre Datenbank weiterhin das App Engine-Dienstkonto zum Importieren oder Exportieren von Daten verwendet, empfehlen wir Ihnen, die Anweisungen in diesem Abschnitt zu befolgen, um zur Verwendung des Cloud Firestore-Dienstagenten zu migrieren.

App Engine-Dienstkonto
PROJECT_ID @appspot.gserviceaccount.com

Der Cloud Firestore-Dienstagent ist vorzuziehen, da er spezifisch für Cloud Firestore ist. Das App Engine-Dienstkonto wird von mehr als einem Dienst gemeinsam genutzt.

Autorisierungskonto anzeigen

Auf der Seite „Import/Export“ in der Google Cloud Platform Console können Sie sehen, welches Konto Ihre Import- und Exportvorgänge zum Autorisieren von Anfragen verwenden. Sie können auch anzeigen, ob Ihre Datenbank bereits den Cloud Firestore-Dienstagenten verwendet.

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.
  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

  4. Sehen Sie sich das Autorisierungskonto neben der Bezeichnung „Import/Export-Jobs ausführen als“ an.

Wenn Ihr Projekt den Cloud Firestore-Dienstagenten nicht verwendet, können Sie mit einer der folgenden Techniken zum Cloud Firestore-Dienstagenten migrieren:

Die erste dieser Techniken ist vorzuziehen, da sie den Wirkungsbereich auf ein einzelnes Cloud Firestore-Projekt beschränkt. Die zweite Technik wird nicht bevorzugt, da sie keine vorhandenen Cloud Storage-Bucket-Berechtigungen migriert. Es bietet jedoch Sicherheitskonformität auf Organisationsebene.

Führen Sie eine Migration durch, indem Sie die Cloud Storage-Bucket-Berechtigungen überprüfen und aktualisieren

Der Migrationsprozess besteht aus zwei Schritten:

  1. Aktualisieren Sie die Cloud Storage-Bucket-Berechtigungen. Einzelheiten finden Sie im folgenden Abschnitt.
  2. Bestätigen Sie die Migration zum Cloud Firestore-Dienstagenten.

Service-Agent-Bucket-Berechtigungen

Für alle Export- oder Importvorgänge, die einen Cloud Storage-Bucket in einem anderen Projekt verwenden, müssen Sie dem Cloud Firestore-Dienstagenten Berechtigungen für diesen Bucket erteilen. Beispielsweise müssen Vorgänge, die Daten in ein anderes Projekt verschieben, auf einen Bucket in diesem anderen Projekt zugreifen. Andernfalls schlagen diese Vorgänge nach der Migration zum Cloud Firestore-Dienstagenten fehl.

Für Import- und Export-Workflows, die innerhalb desselben Projekts bleiben, sind keine Änderungen an den Berechtigungen erforderlich. Der Cloud Firestore-Dienstagent kann standardmäßig auf Buckets im selben Projekt zugreifen.

Aktualisieren Sie die Berechtigungen für Cloud Storage-Buckets aus anderen Projekten, um Zugriff auf den Service-Agenten service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com zu gewähren. Weisen Sie dem Dienstagenten die Rolle Firestore Service Agent zu.

Die Rolle Firestore Service Agent gewährt Lese- und Schreibberechtigungen für einen Cloud Storage-Bucket. Wenn Sie nur Lese- oder nur Schreibberechtigungen erteilen müssen, verwenden Sie eine benutzerdefinierte Rolle .

Der im folgenden Abschnitt beschriebene Migrationsprozess hilft Ihnen dabei, Cloud Storage-Buckets zu identifizieren, die möglicherweise Berechtigungsaktualisierungen erfordern.

Migrieren Sie ein Projekt zum Firestore Service Agent

Führen Sie die folgenden Schritte aus, um vom App Engine-Dienstkonto zum Cloud Firestore-Dienstagenten zu migrieren. Sobald die Migration abgeschlossen ist, kann sie nicht mehr rückgängig gemacht werden.

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.
  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

  4. Wenn Ihr Projekt noch nicht zum Cloud Firestore-Dienstagenten migriert wurde, sehen Sie ein Banner, das die Migration beschreibt, und eine Schaltfläche „Bucket-Status prüfen“ . Der nächste Schritt hilft Ihnen, potenzielle Berechtigungsfehler zu identifizieren und zu beheben.

    Klicken Sie auf Bucket-Status prüfen .

    Es erscheint ein Menü mit der Option zum Abschließen Ihrer Migration und einer Liste der Cloud Storage-Buckets. Es kann einige Minuten dauern, bis die Liste vollständig geladen ist.

    Diese Liste enthält Buckets, die kürzlich in Import- und Exportvorgängen verwendet wurden, dem Cloud Firestore-Dienstagenten jedoch derzeit keine Lese- und Schreibberechtigungen erteilen.

  5. Notieren Sie sich den Hauptnamen des Cloud Firestore-Dienstagenten Ihres Projekts. Der Name des Service-Agenten wird unter dem Service-Agenten angezeigt, um den Zugriff auf die Bezeichnung zu ermöglichen .
  6. Führen Sie für jeden Bucket in der Liste, den Sie für zukünftige Import- oder Exportvorgänge verwenden werden, die folgenden Schritte aus:

    1. Klicken Sie in der Tabellenzeile dieses Buckets auf Fix . Dadurch wird die Berechtigungsseite dieses Buckets in einem neuen Tab geöffnet.

    2. Klicken Sie auf Hinzufügen .
    3. Geben Sie im Feld „Neue Prinzipale“ den Namen Ihres Cloud Firestore-Dienstagenten ein.
    4. Wählen Sie im Feld „Rolle auswählen“ die Option Service Agents > Firestore Service Agent aus.
    5. Klicken Sie auf Speichern .
    6. Kehren Sie zur Registerkarte mit der Seite „Cloud Firestore Import/Export“ zurück.
    7. Wiederholen Sie diese Schritte für andere Buckets in der Liste. Stellen Sie sicher, dass Sie alle Seiten der Liste anzeigen.
  7. Klicken Sie auf Zum Firestore-Dienstagenten migrieren . Wenn Sie immer noch Buckets mit fehlgeschlagenen Berechtigungsprüfungen haben, müssen Sie Ihre Migration bestätigen, indem Sie auf „Migrieren“ klicken.

    Eine Benachrichtigung informiert Sie, wenn Ihre Migration abgeschlossen ist. Die Migration kann nicht rückgängig gemacht werden.

Migrationsstatus anzeigen

So überprüfen Sie den Migrationsstatus Ihres Projekts:

  1. Gehen Sie in der Google Cloud Platform Console zur Seite „Datenbanken“ .

    Gehen Sie zu Datenbanken

  2. Wählen Sie aus der Liste der Datenbanken die gewünschte Datenbank aus.
  3. Klicken Sie im Navigationsmenü auf Importieren/Exportieren .

  4. Suchen Sie nach dem Prinzipal neben der Bezeichnung „Import/Export-Jobs ausführen als “.

    Wenn der Prinzipal service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com ist, wurde Ihr Projekt bereits zum Cloud Firestore-Dienstagenten migriert. Die Migration kann nicht rückgängig gemacht werden.

    Wenn das Projekt nicht migriert wurde, wird oben auf der Seite ein Banner mit der Schaltfläche „Bucket-Status prüfen“ angezeigt. Informationen zum Abschließen der Migration finden Sie unter „Migration zum Firestore-Dienstagenten“ .

Fügen Sie eine organisationsweite Richtlinieneinschränkung hinzu

  • Legen Sie in der Richtlinie Ihrer Organisation die folgende Einschränkung fest:

    Erfordern Sie den Firestore-Dienstagenten für den Import/Export ( firestore.requireP4SAforImportExport ).

    Diese Einschränkung erfordert, dass Import- und Exportvorgänge den Cloud Firestore-Dienstagenten zum Autorisieren von Anforderungen verwenden. Informationen zum Festlegen dieser Einschränkung finden Sie unter Erstellen und Verwalten von Organisationsrichtlinien .

Durch die Anwendung dieser organisatorischen Richtlinieneinschränkung werden nicht automatisch die entsprechenden Cloud Storage-Bucket-Berechtigungen für den Cloud Firestore-Dienstagenten gewährt.

Wenn die Einschränkung Berechtigungsfehler für Import- oder Export-Workflows verursacht, können Sie sie deaktivieren, um wieder das Standarddienstkonto zu verwenden. Nachdem Sie die Cloud Storage-Bucket-Berechtigungen überprüft und aktualisiert haben , können Sie die Einschränkung erneut aktivieren.