Amazon S3-Übertragungen

Mit BigQuery Data Transfer Service für Amazon S3 können Sie wiederkehrende Ladejobs von Amazon S3 in BigQuery automatisch planen und verwalten.

Vorbereitung

Bevor Sie eine Amazon S3-Übertragung erstellen, sind folgende Schritte erforderlich:

Beschränkungen

Amazon S3-Übertragungen unterliegen den folgenden Beschränkungen:

  • Der Bucket-Teil des Amazon S3-URI kann nicht parametrisiert werden.
  • Bei Übertragungen von Amazon S3 mit dem auf WRITE_TRUNCATE eingestellten Parameter Schreibanordnung werden bei jeder Ausführung alle übereinstimmenden Dateien in Google Cloud übertragen. Dies kann zu zusätzlichen Kosten für die ausgehende Amazon S3-Datenübertragung führen. Weitere Informationen dazu, welche Dateien während einer Ausführung übertragen werden, finden Sie unter Auswirkungen von Präfixabgleichen gegenüber Platzhalterabgleichen.
  • Übertragungen aus AWS GovCloud-Regionen (us-gov) werden nicht unterstützt.
  • Übertragungen an BigQuery Omni-Standorte werden nicht unterstützt.

  • Je nach Format Ihrer Amazon S3-Quelldaten sind weitere Beschränkungen möglich. Weitere Informationen erhalten Sie hier:

  • Das Standardintervall für wiederkehrende Übertragungen beträgt 24 Stunden. Das Standardintervall für eine wiederkehrende Übertragung beträgt 24 Stunden.

Erforderliche Berechtigungen

Vor dem Erstellen einer Amazon S3-Übertragung sind folgende Schritte erforderlich:

  • Sorgen Sie dafür, dass die Person, die die Übertragung erstellt, die folgenden Berechtigungen in BigQuery hat:

    • bigquery.transfers.update Berechtigungen zum Erstellen der Übertragung
    • Die Berechtigungen bigquery.datasets.get und bigquery.datasets.update für das Ziel-Dataset

    Die vordefinierte IAM-Rolle bigquery.admin enthält die Berechtigungen bigquery.transfers.update, bigquery.datasets.update und bigquery.datasets.get. Weitere Informationen zu IAM-Rollen in BigQuery Data Transfer Service finden Sie in der Zugriffssteuerung.

  • Prüfen Sie anhand der Dokumentation zu Amazon S3, ob Sie alle erforderlichen Berechtigungen zum Aktivieren der Übertragung konfiguriert haben. Auf die Amazon S3-Quelldaten muss mindestens die AWS-Verwaltungsrichtlinie AmazonS3ReadOnlyAccess angewendet werden.

Eine Amazon S3-Datenübertragung einrichten

Führen Sie zum Erstellen einer Amazon S3-Datenübertragung folgende Schritte aus:

Console

  1. Rufen Sie in der Google Cloud Console die Seite "BigQuery" auf.

    Zur Seite „BigQuery“

  2. Klicken Sie auf Übertragungen.

  3. Klicken Sie auf Übertragung erstellen.

  4. Auf der Seite Übertragung erstellen:

    • Wählen Sie im Abschnitt Source type (Quelltyp) für Source (Quelle) die Option Amazon S3 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

    • Im Abschnitt Zeitplanoptionen:

      • Wählen Sie eine Wiederholungshäufigkeit aus. Wenn Sie Stunden, Tage, Wochen oder Monate auswählen, müssen Sie auch eine Häufigkeit angeben. Sie können auch Benutzerdefiniert auswählen, um eine spezifischere Wiederholungshäufigkeit zu erstellen. Wenn Sie On-Demand auswählen, wird diese Übertragung nur ausgeführt, wenn Sie die Übertragung manuell auslösen.

      • Wählen Sie gegebenenfalls Jetzt starten oder Zum festgelegten Zeitpunkt starten aus und geben Sie ein Startdatum und eine Laufzeit an.

    • 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

    • Im Abschnitt Data source details:

      • Geben Sie für Destination table (Zieltabelle) den Namen der Tabelle ein, die Sie zum Speichern Ihrer Daten in BigQuery erstellt haben. In Namen von Zieltabellen sind auch Parameter möglich.
      • Für Amazon S3-URI geben Sie den URI im folgenden Format ein s3://mybucket/myfolder/.... In URIs sind auch Parameter möglich.
      • Geben Sie für die Access key ID (Zugangsschlüssel-ID) Ihre Zugangsschlüssel-ID ein.
      • Geben Sie für Secret access key (geheimer Zugriffsschlüssel) Ihren geheimen Zugriffsschlüssel ein.
      • Wählen Sie für File format (Dateiformat) Ihr Datenformat aus: newline delimited JSON (durch Zeilenumbruch getrennte JSON), Avro, Parquet oder ORC.

      • Wählen Sie unter Schreibanordnung eine der folgenden Optionen aus:

        • WRITE_APPEND, um neue Daten schrittweise an Ihre vorhandene Zieltabelle anzuhängen. WRITE_APPEND ist der Standardwert für die Schreibeinstellung.
        • WRITE_TRUNCATE, um Daten in der Zieltabelle bei jeder Übertragungsausführung zu überschreiben.

        Weitere Informationen dazu, wie BigQuery Data Transfer Service Daten mit WRITE_APPEND oder WRITE_TRUNCATE aufnimmt, finden Sie unter Datenaufnahme für Amazon S3-Übertragungen Weitere Informationen zum Feld writeDisposition erhalten Sie unter JobConfigurationLoad.

        Details zur S3-Quelle

    • Im Bereich Übertragungsoptionen – alle Formate gehen Sie so vor:

      • Geben Sie unter Anzahl zulässiger Fehler einen ganzzahligen Wert für die maximale Anzahl der fehlerhaften Datensätze ein, die ignoriert werden können.
      • (Optional) Geben Sie unter Dezimalzieltypen eine durch Kommas getrennte Liste möglicher SQL-Datentypen ein, in die Quelldezimalwerte konvertiert werden können. Welcher SQL-Datentyp für die Konvertierung ausgewählt wird, hängt von folgenden Bedingungen ab:
        • Der für die Konvertierung 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 aufgelisteten Datentypen die Genauigkeit und die Skalierung unterstützt, wird der Datentyp ausgewählt, der den in der angegebenen Liste breitesten Bereich unterstützt. Geht ein Wert beim Lesen der Quelldaten über den unterstützten Wert hinaus, wird ein Fehler ausgegeben.
        • Der Datentyp STRING unterstützt alle Genauigkeits- und Skalierungswerte.
        • Wenn dieses Feld leer bleibt, wird der Datentyp standardmäßig auf „NUMERIC,STRING“ für ORC und „NUMERIC“ für die anderen Dateiformate gesetzt.
        • Dieses Feld darf keine doppelten Datentypen enthalten.
        • Die Reihenfolge der Datentypen, die Sie in diesem Feld auflisten, wird ignoriert.

      Übertragungsoptionen, alle Formate

    • Wenn Sie als Dateiformat CSV oder JSON ausgewählt haben, aktivieren Sie im Abschnitt JSON, CSV die Option Ignore unknown values (Unbekannte Werte ignorieren), um Zeilen zu akzeptieren, die Werte enthalten, die nicht mit dem Schema übereinstimmen. Unbekannte Werte werden ignoriert. Bei CSV-Dateien werden zusätzliche Werte am Ende einer Zeile ignoriert.

      Unbekannte Werte ignorieren

    • Wenn Sie als Dateiformat CSV oder JSON ausgewählt haben, geben Sie im Abschnitt CSV weitere CSV-Optionen zum Laden von Daten ein.

      CSV-Optionen

    • Wählen Sie im Menü Dienstkonto ein Dienstkonto aus den Dienstkonten aus, die mit Ihrem Google Cloud-Projekt verknüpft sind. Sie können Ihre Übertragung mit einem Dienstkonto verknüpfen, anstatt Ihre Nutzeranmeldedaten zu verwenden. Weitere Informationen zur Verwendung von Dienstkonten mit Datenübertragungen finden Sie unter Dienstkonten verwenden.

    • (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 für Select a Pub/Sub topic den Namen Ihres Themas aus oder klicken Sie auf Create a topic, um eines zu 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 das Flag --transfer_config für die Übertragungserstellung an.

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

Dabei gilt:

  • project_id: Optional. Ihre Google Cloud-Projekt-ID. Wenn --project_id nicht bereitgestellt wird, um ein bestimmtes Projekt anzugeben, wird das Standardprojekt verwendet.
  • data_source: Erforderlich. Die Datenquelle: amazon_s3.
  • display_name: Erforderlich. Der Anzeigename für die Übertragungskonfiguration. Der Übertragungsname kann ein beliebiger Wert sein, mit dem Sie die Übertragung identifizieren können, wenn Sie sie später ändern müssen.
  • dataset: erforderlich. Das Ziel-Dataset für die Übertragungskonfiguration.
  • service_account: Der Name des Dienstkontos, mit dem die Übertragung authentifiziert wird. Das Dienstkonto sollte zum selben project_id gehören, das für die Erstellung der Übertragung verwendet wurde, und sollte alle erforderlichen Berechtigungen haben.

  • parameters: erforderlich. Die Parameter für die erstellte Übertragungskonfiguration im JSON-Format. Beispiel: --params='{"param":"param_value"}'. Im Folgenden finden Sie die Parameter für eine Amazon S3-Übertragung:

    • destination_table_name_template: Erforderlich. Der Name der Zieltabelle.

    • data_path: Erforderlich. Der Amazon S3-URI im folgenden Format:

      s3://mybucket/myfolder/...

      In URIs sind auch Parameter möglich.

    • access_key_id: Erforderlich. Ihre Zugriffsschlüssel-ID.

    • secret_access_key: Erforderlich. Ihr geheimer Zugriffsschlüssel.

    • file_format: Optional. Gibt den Typ der Dateien an, die Sie übertragen möchten: CSV, JSON, AVRO, PARQUET oder ORC. Der Standardwert ist CSV.

    • write_disposition: Optional. WRITE_APPEND überträgt nur die Dateien, die seit der letzten erfolgreichen Ausführung geändert wurden. WRITE_TRUNCATE überträgt alle übereinstimmenden Dateien, einschließlich Dateien, die bei einer vorherigen Ausführung übertragen wurden. Der Standardwert ist WRITE_APPEND.

    • max_bad_records: Optional. Die Anzahl der zulässigen ungültigen Datensätze. Der Standardwert ist 0.

    • decimal_target_types: Optional. Eine durch Kommas getrennte Liste möglicher SQL-Datentypen, in die die Dezimalwerte der Quelle konvertiert werden können. Wenn dieses Feld nicht angegeben ist, wird der Datentyp standardmäßig auf "NUMERIC, STRING" für ORC und "NUMERIC" für die anderen Dateiformate festgelegt.

    • ignore_unknown_values: Optional und wird ignoriert, wenn file_format nicht JSON oder CSV ist. Gibt an, ob unbekannte Werte in Ihren Daten ignoriert werden sollen.

    • field_delimiter: Optional und gilt nur, wenn file_format gleich CSV ist. Das Zeichen, das Felder trennt. Der Standardwert ist ein Komma.

    • skip_leading_rows: Optional und gilt nur, wenn file_format gleich CSV ist. Gibt die Anzahl der Kopfzeilen an, die nicht importiert werden sollen. Der Standardwert ist 0.

    • allow_quoted_newlines: Optional und gilt nur, wenn file_format gleich CSV ist. Gibt an, ob Zeilenumbrüche in Feldern in Anführungszeichen zulässig sind.

    • allow_jagged_rows: Optional und gilt nur, wenn file_format gleich CSV ist. Gibt an, ob Zeilen ohne nachgestellte optionale Spalten zulässig sind. Die fehlenden Werte werden mit NULL gefüllt.

Mit dem folgenden Befehl wird beispielsweise eine Amazon S3-Übertragung mit dem Namen My Transfer erstellt. Dabei werden ein data_path mit einem Wert von s3://mybucket/myfile/*.csv, das Ziel-Dataset mydataset und bei file_format das Dateiformat 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":"s3://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"write_disposition":"WRITE_APPEND",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false"}' \
--data_source=amazon_s3

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

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 

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 amazon s3 transfer config.
public class CreateAmazonS3Transfer {

  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";
    // Amazon S3 Bucket Uri with read role permission
    String sourceUri = "s3://your-bucket-name/*";
    String awsAccessKeyId = "MY_AWS_ACCESS_KEY_ID";
    String awsSecretAccessId = "AWS_SECRET_ACCESS_ID";
    String sourceFormat = "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", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("access_key_id", Value.newBuilder().setStringValue(awsAccessKeyId).build());
    params.put("secret_access_key", Value.newBuilder().setStringValue(awsSecretAccessId).build());
    params.put("source_format", Value.newBuilder().setStringValue(sourceFormat).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 Aws S3 Config Name")
            .setDataSourceId("amazon_s3")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createAmazonS3Transfer(projectId, transferConfig);
  }

  public static void createAmazonS3Transfer(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("Amazon s3 transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Amazon s3 transfer was not created." + ex.toString());
    }
  }
}

Auswirkungen von Präfixabgleichen gegenüber Platzhalterabgleichen

Die Amazon S3 API unterstützt den Präfixabgleich, nicht aber den Platzhalterabgleich. Alle Amazon S3-Dateien, die mit einem Präfix übereinstimmen, werden in Google Cloud übertragen. Dabei werden jedoch nur die Dateien in BigQuery geladen, die mit der Amazon S3-URI in der Übertragungskonfiguration übereinstimmen. Das kann zu übermäßigen Kosten bei der ausgehenden Amazon S3-Datenübertragung für Dateien führen, die zwar übertragen, aber nicht in BigQuery geladen werden.

Sehen Sie sich als Beispiel diesen Datenpfad an:

s3://bucket/folder/*/subfolder/*.csv

Zusammen mit diesen Dateien am Quellspeicherort:

s3://bucket/folder/any/subfolder/file1.csv
s3://bucket/folder/file2.csv

Damit werden alle Amazon S3-Dateien mit dem Präfix s3://bucket/folder/ an Google Cloud übertragen. In diesem Beispiel werden file1.csv und file2.csv übertragen.

Es werden aber nur Dateien, die mit s3://bucket/folder/*/subfolder/*.csv übereinstimmen, in BigQuery geladen. In diesem Beispiel wird nur file1.csv in BigQuery geladen.

Fehler bei der Übertragungseinrichtung beheben

Falls beim Einrichten von Übertragungen Probleme auftreten, finden Sie unter Übertragungsprobleme mit Amazon S3 weitere Informationen.

Nächste Schritte