Cloud Storage-Übertragungen

Mit dem BigQuery Data Transfer Service für Cloud Storage können Sie wiederkehrende Datenübertragungen von Cloud Storage zu BigQuery planen.

Hinweis

Führen Sie vor dem Erstellen einer Cloud Storage-Übertragung Folgendes aus:

Beschränkungen

Für wiederkehrende Übertragungen von Cloud Storage nach BigQuery gelten die folgenden Beschränkungen:

  • Alle Dateien, die entweder durch einen Platzhalter oder durch Laufzeitparameter für Ihre Übertragung definiert wurden, müssen dasselbe Schema verwenden, das Sie für die Zieltabelle definiert haben. Sonst schlägt die Übertragung fehl. Wenn das Tabellenschema zwischen zwei Ausführungen geändert wird, schlägt die Übertragung ebenfalls fehl.
  • Cloud Storage-Objekte können versioniert werden. Deshalb ist zu beachten, dass archivierte Cloud Storage-Objekte für BigQuery-Übertragungen nicht unterstützt werden. Objekte müssen für die Übertragung live sein.
  • Im Unterschied zur Übertragung einzelner Datenlasten von Cloud Storage zu BigQuery müssen Sie für fortlaufende Übertragungen vor dem Einrichten die Zieltabelle und ihr Schema erstellen. BigQuery kann die Tabelle nicht als Teil des wiederkehrenden Datenübertragungsprozesses erstellen.
  • Übertragungen aus Cloud Storage werden immer mit der WRITE_APPEND-Präferenz ausgelöst, die Daten an die Zieltabelle anhängt. Weitere Informationen hierzu finden Sie unter configuration.load.writeDisposition in der load-Jobkonfiguration.
  • BigQuery Data Transfer Service garantiert nicht, dass alle Dateien übertragen oder nur einmal übertragen werden, wenn während der Übertragung auf die Cloud Storage-Dateien zugegriffen wird.
  • Wenn für den Speicherort Ihres Datasets ein anderer Wert als US festgelegt ist, muss sich der regionale oder multiregionale Cloud Storage-Bucket in derselben Region wie das Dataset befinden.
  • BigQuery Data Transfer Service garantiert keine Datenkonsistenz für externe Datenquellen. Werden die zugrunde liegenden Daten während der Ausführung der Abfrage geändert, kann dies zu einem unerwarteten Verhalten führen.

  • Je nach Format Ihrer Cloud Storage-Quelldaten sind weitere Beschränkungen möglich. Weitere Informationen:

  • Ihr Cloud Storage-Bucket muss sich in einer Region oder in mehreren Regionen befinden, die mit der Region oder mit dem multiregionalen Standort des Ziel-Datasets in BigQuery kompatibel ist bzw. sind. Dies wird als Colocation bezeichnet. Ausführliche Informationen zur Cloud Storage-Übertragung finden Sie unter Datenspeicherorte.

Mindestintervalle

  • Quelldateien in Cloud Storage müssen mindestens eine Stunde alt sein, damit sie übertragen werden können.
  • Der Mindestabstand zwischen wiederkehrenden Überweisungen beträgt 1 Stunde. Das Standardintervall für wiederkehrende Übertragungen beträgt 24 Stunden.

Erforderliche Berechtigungen

Wenn Sie Daten in BigQuery laden, benötigen Sie Berechtigungen zum Laden von Daten in neue oder vorhandene BigQuery-Tabellen und -Partitionen. Wenn Sie Daten aus Cloud Storage laden, benötigen Sie auch Zugriff auf den Bucket, der Ihre Daten enthält. Prüfen Sie, ob Sie die folgenden erforderlichen Berechtigungen haben:

  • BigQuery: Zum Erstellen der geplanten Übertragung werden Berechtigungen vom Typ bigquery.transfers.update benötigt. Die vordefinierte IAM-Rolle bigquery.admin enthält diese Berechtigungen vom Typ bigquery.transfers.update. Weitere Informationen zu IAM-Rollen in BigQuery Data Transfer Service finden Sie unter Referenz zur Zugriffssteuerung.
  • Cloud Storage: storage.objects.get Es sind Berechtigungen für die einzelnen Buckets oder höhere Berechtigungen erforderlich. Wenn Sie einen URI-Platzhalter verwenden, benötigen Sie außerdem Berechtigungen des Typs storage.objects.list. Wenn Sie die Quelldateien nach jeder erfolgreichen Übertragung löschen möchten, benötigen Sie außerdem Berechtigungen vom Typ storage.objects.delete. Die vordefinierte Cloud IAM-Rolle storage.objectAdmin enthält alle diese Berechtigungen.

Cloud Storage-Übertragung einrichten

So erstellen Sie eine Cloud Storage-Übertragung im BigQuery Data Transfer Service:

Console

  1. Rufen Sie in der Cloud Console die Seite „BigQuery“ auf.

    Zur Seite „BigQuery“

  2. Klicken Sie auf Übertragungen.

  3. Klicken Sie auf Create (Erstellen).

  4. Auf der Seite Create Transfer (Übertragung erstellen):

    • Wählen Sie im Abschnitt Source type (Quelltyp) für Source (Quelle) die Option Cloud Storage aus.

      Übertragungsquelle

    • Geben Sie im Abschnitt Transfer config name (Konfigurationsname für Übertragung) für Display name (Anzeigename) einen Namen wie My Transfer für die Übertragung ein. Der Übertragungsname kann ein beliebiger Wert sein, mit dem Sie die Übertragung einfach identifizieren können, wenn Sie sie später ändern müssen.

      Name der Übertragung

    • Übernehmen Sie im Abschnitt Schedule options (Zeitplanoptionen) für Schedule (Zeitplan) den Standardwert (Start now) (Jetzt starten) oder klicken Sie auf Start at a set time (Zu einer festgelegten Zeit starten).

      • Wählen Sie für Repeats (Wiederholungen) eine Option aus, um festzulegen, wie oft die Übertragung ausgeführt werden soll. Das Mindestintervall beträgt 1 Stunde.
        • Täglich (Standardeinstellung)
        • Weekly (Wöchentlich)
        • Monthly (Monatlich)
        • Custom (Benutzerdefiniert)
        • On demand
      • Geben Sie für Start date and run time (Startdatum und Laufzeit) das Datum und die Uhrzeit für den Beginn der Übertragung ein. Wenn Sie Start now (Jetzt starten) auswählen, ist diese Option deaktiviert.

        Zeitplan für die Übertragung

    • Wählen Sie im Abschnitt Destination settings (Zieleinstellungen) für Destination dataset (Ziel-Dataset) das Dataset aus, das Sie zum Speichern Ihrer Daten erstellt haben.

      Dataset übertragen

    • Führen Sie im Abschnitt Details zur Datenquelle Folgendes aus:

      • Geben Sie für Destination table (Zieltabelle) den Namen Ihrer Zieltabelle ein. Die Zieltabelle muss den Regeln für die Tabellenbenennung folgen. Als Namen von Zieltabellen sind auch Parameter möglich.
      • Geben Sie unter Cloud Storage-URI den Cloud Storage-URI ein. Dafür werden Platzhalter und Parameter unterstützt.
      • Wählen Sie unter Schreibeinstellung eine der folgenden Optionen aus:

        • APPEND, um neue Daten an die vorhandene Zieltabelle anzuhängen, oder
        • MIRROR, um Daten in der Zieltabelle zu aktualisieren, damit die geänderten Daten in der Quelle widergespiegelt werden. MIRROR überschreibt eine neue Kopie der Daten in der Zieltabelle.
      • Klicken Sie auf das Kästchen Quelldateien nach Übertragung löschen, wenn Sie die Quelldateien nach jeder erfolgreichen Übertragung löschen möchten. Für Löschjobs besteht keine Erfolgsgarantie. Löschjobs werden nicht noch einmal versucht, wenn der erste Versuch zum Löschen der Quelldateien fehlschlägt.

      • Im Abschnitt Transfer Options (Übertragungsoptionen):

        • Unter All Formats (Alle Formate):
          • Geben Sie unter Number of errors allowed (Anzahl zulässiger Fehler) die maximale Anzahl fehlerhafter Datensätze ein, die BigQuery beim Ausführen des Jobs ignorieren kann. Wenn die Anzahl fehlerhafter Datensätze diesen Wert überschreitet, wird im Jobergebnis "ungültig" zurückgegeben und der Job schlägt fehl. Der Standardwert ist 0.
        • Unter JSON, CSV:
          • Klicken Sie das Kästchen Ignore unknown values (Unbekannte Werte ignorieren) an, wenn bei der Übertragung Daten ignoriert werden sollen, die nicht in das Schema der Zieltabelle passen.
        • Unter CSV:

          • Geben Sie unter Field delimiter (Feldtrennzeichen) das Zeichen ein, das die Felder trennt. Der Standardwert ist ein Komma.
          • Geben Sie unter Header rows to skip (Zu überspringende Kopfzeilen) die Anzahl der Kopfzeilen in den Quelldateien ein, wenn Sie diese nicht importieren möchten. Der Standardwert ist 0.
          • Klicken Sie das Kästchen Allow quoted newlines (Zeilenumbrüche in Abschnitten in Anführungszeichen zulassen) an, wenn Sie Zeilenumbrüche innerhalb von Feldern in Anführungszeichen zulassen möchten.
          • Klicken Sie auf das Kästchen Unvollständige Zeilen zulassen, wenn Sie die Übertragung von Zeilen mit fehlenden NULLABLE-Spalten erlauben möchten.

      Details zur Cloud Storage-Quelle

    • Optional: Im Abschnitt Notification options (Benachrichtigungsoptionen):

      • Klicken Sie auf die Umschaltfläche, um E-Mail-Benachrichtigungen zu aktivieren. Wenn Sie diese Option aktivieren, erhält der Übertragungsadministrator eine E-Mail-Benachrichtigung, wenn ein Übertragungsvorgang fehlschlägt.
      • Wählen Sie unter Cloud Pub/Sub-Thema auswählen Ihr Thema aus oder klicken Sie auf Thema erstellen. Mit dieser Option werden Pub/Sub-Ausführungsbenachrichtigungen für Ihre Übertragung konfiguriert.
  5. Klicken Sie auf Speichern.

bq

Geben Sie den Befehl bq mk ein und geben Sie dabei das Flag --transfer_config für das Erstellen der Übertragung an. Die folgenden Flags sind ebenfalls erforderlich:

  • --data_source
  • --display_name
  • --target_dataset
  • --params
bq mk \
--transfer_config \
--project_id=project_id \
--data_source=data_source \
--display_name=name \
--target_dataset=dataset \
--params='parameters'

Dabei gilt:

  • project_id ist die Projekt-ID. Wird --project_id für ein bestimmtes Projekt nicht angegeben, wird das Standardprojekt verwendet.
  • data_source ist die Datenquelle: google_cloud_storage.
  • name ist der Anzeigename für die Übertragungskonfiguration. Der Name der Übertragung kann ein beliebiger Wert sein, mit dem Sie die Übertragung einfach ermitteln können, wenn Sie sie später ändern müssen.
  • dataset ist das Ziel-Dataset für die Übertragungskonfiguration.
  • parameters enthält die Parameter für die erstellte Übertragungskonfiguration im JSON-Format. Beispiel: --params='{"param":"param_value"}'.
    • Für Cloud Storage müssen Sie die Parameter data_path_template, destination_table_name_template und file_format angeben. data_path_template ist der Cloud Storage-URI, der die zu übertragenden Dateien enthält, und kann genau einen Platzhalter enthalten. destination_table_name_template ist der Name Ihrer Zieltabelle. Geben Sie für file_format den Typ der Dateien an, den Sie übertragen möchten: CSV, JSON, AVRO, PARQUET oder ORC. Der Standardwert ist CSV.
    • Für alle "file_format"-Werte können Sie den optionalen Parameter max_bad_records angeben. Der Standardwert ist 0.
    • Für die JSON- oder CSV-Werte in "file_format" können Sie den optionalen Parameter ignore_unknown_values angeben. Dieser Parameter wird ignoriert, wenn Sie für file_format nicht CSV oder JSON ausgewählt haben.
    • Für CSV in "file_format" können Sie den optionalen Parameter field_delimiter für das Zeichen angeben, mit dem Felder voneinander getrennt werden. Der Standardwert ist ein Komma. Dieser Parameter wird ignoriert, wenn Sie für file_format nicht CSV ausgewählt haben.
    • Für CSV in "file_format" können Sie den optionalen Parameter skip_leading_rows einschließen, um Kopfzeilen anzugeben, die Sie nicht importieren möchten. Der Standardwert ist 0. Dieser Parameter wird ignoriert, wenn Sie für file_format nicht CSV ausgewählt haben.
    • Für CSV in "file_format" können Sie den optionalen Parameter allow_quoted_newlines angeben, wenn Sie innerhalb von Anführungszeichen Zeilenumbrüche zulassen möchten. Dieser Parameter wird ignoriert, wenn Sie für file_format nicht CSV ausgewählt haben.
    • Für CSV in "file_format" können Sie den optionalen Parameter allow_jagged_rows angeben, wenn Sie Zeilen akzeptieren möchten, bei denen optionale Spalten am Ende fehlen. Die fehlenden Werte werden mit NULL gefüllt. Dieser Parameter wird ignoriert, wenn Sie für file_format nicht CSV ausgewählt haben.
    • Der optionale Parameter delete_source_files löscht die Quelldateien nach jeder erfolgreichen Übertragung. Das Löschen von Jobs wird nicht noch einmal versucht, wenn der erste Versuch zum Löschen der Quelldateien fehlschlägt. Der Standardwert für delete_source_files ist „false“.

Mit dem folgenden Befehl wird beispielsweise eine Cloud Storage-Übertragung mit dem Namen My Transfer erstellt. Dabei wird für data_path_template der Wert gs://mybucket/myfile/*.csv, als Ziel-Dataset mydataset und für file_format der Wert CSV verwendet. Dieses Beispiel enthält nicht standardmäßige Werte für die optionalen Parameter, die dem CSV-Dateiformat zugeordnet sind.

Die Übertragung wird im Standardprojekt erstellt:

bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path_template":"gs://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage

Nachdem Sie den Befehl ausgeführt haben, erhalten Sie eine Meldung wie die Folgende:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

Folgen Sie der Anleitung und fügen Sie den Authentifizierungscode in die Befehlszeile ein.

API

Verwenden Sie die Methode projects.locations.transferConfigs.create und geben Sie eine Instanz der Ressource TransferConfig an.

Aktualisierungsausführung einer Übertragung einrichten

Zusätzlich zum Einrichten einer wiederkehrenden Übertragung von Cloud Storage können Sie auch eine Aktualisierungsausführung einrichten, um zusätzliche Datendateien abzurufen.

Wenn die Übertragungskonfiguration datumsbezogen (parametrisiert) und/oder der Cloud Storage-URI parametrisiert ist, können Sie die Aktualisierung für bestimmte Daten ausführen.

So richten Sie eine Aktualisierungsübertragung ein:

Console

  1. Rufen Sie in der Cloud Console die Seite „BigQuery“ auf.

    Zur Seite „BigQuery“

  2. Klicken Sie auf Übertragungen.

  3. Klicken Sie auf Ihre Übertragung.

  4. Klicken Sie auf das Menü Mehr und wählen Sie Übertragung aktualisieren aus.

  5. Wählen Sie im Dialogfeld Planen Sie eine Backfill-Ausführung Termine für Startdatum und Enddatum aus.

    Aktualisierungstermine festlegen

Weitere Informationen