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:

Prüfen Sie, ob Sie alle erforderlichen Aktionen zum Aktivieren von BigQuery Data Transfer Service ausgeführt haben.
Rufen Sie Ihren Cloud Storage-URI ab.
Erstellen Sie ein BigQuery-Dataset zum Speichern Ihrer Daten.
Erstellen Sie die Zieltabelle für Ihre Übertragung und geben Sie die Schemadefinition an.

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 Einstellung WRITE_APPEND ausgelöst. Damit werden die Daten an die Zieltabelle angefügt. Weitere Informationen finden Sie in der Beschreibung des Felds writeDisposition des Objekts JobConfigurationLoad.
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 werden sofort zur Übertragung freigegeben, ohne dass ein Mindestalter für die Datei gilt.
Der Mindestabstand zwischen wiederkehrenden Überweisungen beträgt 15 Minuten. 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

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

Zur Seite „BigQuery“
Klicken Sie auf Übertragungen.
Klicken Sie auf Create (Erstellen).
Auf der Seite Create Transfer (Übertragung erstellen):
- Wählen Sie im Abschnitt Source type (Quelltyp) für Source (Quelle) die Option Cloud Storage aus.
- 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.
- Ü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 15 Minuten.
    - Täglich (Standardeinstellung)
    - Wöchentlich
    - Monatlich
    - Benutzerdefiniert: Geben Sie für Benutzerdefinierter Zeitplan eine benutzerdefinierte Häufigkeit ein. z. B. every day 00:00. Siehe Zeitplan formatieren.
    - 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.
- 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.
- 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.
    Hinweis: Wenn Ihre Angaben im Feld Cloud Storage-URI keiner Datei entsprechen, werden die Daten in der Zieltabelle nicht aktualisiert (überschrieben).
  - 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.
      - (Optional) Geben Sie unter Dezimalzieltypen eine durch Kommas getrennte Liste möglicher SQL-Datentypen ein, in die die Quell-Dezimalwerte umgewandelt werden können. Welcher SQL-Datentyp für die Conversion ausgewählt wird, hängt von den folgenden Bedingungen ab:
        
        Der für die Conversion ausgewählte Datentyp ist der erste Datentyp in der folgenden Liste, der die Genauigkeit und die Skalierung der Quelldaten in dieser Reihenfolge unterstützt: NUMERIC, BIGNUMERIC und STRING.
        
        Wenn keiner der aufgeführten Datentypen die Genauigkeit und die Skalierung unterstützt, wird der Datentyp ausgewählt, der den größten Bereich der angegebenen Liste unterstützt. Wenn ein Wert beim Lesen der Quelldaten einen unterstützten Bereich überschreitet, wird ein Fehler ausgegeben.
        
        Der Datentyp STRING unterstützt alle Werte für Genauigkeit und Skalierung.
        
        Wenn dieses Feld leer bleibt, wird für ORC standardmäßig der Datentyp "NUMERIC, STRING" und für die anderen Dateiformate "NUMERIC" verwendet.
        
        Dieses Feld darf keine doppelten Datentypen enthalten.
        
        Die Reihenfolge der Datentypen, die Sie in diesem Feld auflisten, wird ignoriert.
    - 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.
      Hinweis: Weitere Informationen finden Sie unter CSV-Optionen.
- 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 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.
Klicken Sie auf Speichern.

bq

Geben Sie den Befehl bq mk ein und geben Sie das Flag --transfer_config für die Übertragungserstellung 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 alle "file_format"-Werte können Sie den optionalen Parameter decimal_target_types angeben. decimal_target_types ist eine durch Kommas getrennte Liste möglicher SQL-Datentypen, in die die Dezimalwerte der Quelle umgewandelt werden können. Wenn dieses Feld nicht angegeben wird, wird für ORC standardmäßig der Datentyp "NUMERIC, STRING" für ORC und "NUMERIC" für die anderen Dateiformate verwendet.
- 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.

Java

Auf GitHub ansehen Feedback

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create google cloud storage transfer config
public class CreateCloudStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    // GCS Uri
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    String fileFormat = "CSV";
    String fieldDelimiter = ",";
    String skipLeadingRows = "1";
    Map<String, Value> params = new HashMap<>();
    params.put(
        "destination_table_name_template", Value.newBuilder().setStringValue(tableId).build());
    params.put("data_path_template", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("write_disposition", Value.newBuilder().setStringValue("APPEND").build());
    params.put("file_format", Value.newBuilder().setStringValue(fileFormat).build());
    params.put("field_delimiter", Value.newBuilder().setStringValue(fieldDelimiter).build());
    params.put("skip_leading_rows", Value.newBuilder().setStringValue(skipLeadingRows).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Google Cloud Storage Config Name")
            .setDataSourceId("google_cloud_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createCloudStorageTransfer(projectId, transferConfig);
  }

  public static void createCloudStorageTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Cloud storage transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Cloud storage transfer was not created." + ex.toString());
    }
  }
}

Übertragung manuell auslösen

Zusätzlich zu automatisch geplanten Übertragungen aus Cloud Storage können Sie manuell eine Übertragung auslösen, um zusätzliche Datendateien zu laden.

Wenn die Übertragungskonfiguration Laufzeit parametrisiert wird, müssen Sie einen Zeitraum angeben, für den zusätzliche Übertragungen gestartet werden.

So lösen Sie eine Übertragung manuell aus:

Console

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

Zur Seite "BigQuery"
Klicken Sie auf Datenübertragung.
Klicken Sie auf Ihre Übertragung.
Klicken Sie auf RUN NOW NOW (ÜBERTRAGUNG FÜHREN) oder auf ZEITPLAN ABFÜHREN (für parametrisierte Übertragungskonfigurationen).
Wählen Sie gegebenenfalls Startdatum und Enddatum aus und klicken Sie zur Bestätigung auf OK.

Bei Laufzeitkonfigurationen mit parametrisierter Übertragung werden Datumsoptionen angezeigt, wenn Sie auf Schedule BACKfill klicken.

Cloud Storage-Übertragungen

Hinweis

Beschränkungen

Mindestintervalle

Erforderliche Berechtigungen

Cloud Storage-Übertragung einrichten

Console

bq

API

Java

Übertragung manuell auslösen

Console

Nächste Schritte