Trasferimenti di Amazon S3

BigQuery Data Transfer Service per Amazon S3 consente di pianificare e gestire job di caricamento ricorrenti da Amazon S3 in BigQuery.

Prima di iniziare

Prima di creare un trasferimento Amazon S3:

Limitazioni

I trasferimenti Amazon S3 sono soggetti alle seguenti limitazioni:

Autorizzazioni obbligatorie

Prima di creare un trasferimento Amazon S3:

  • Assicurati che la persona che crea il trasferimento abbia quanto segue richiesto autorizzazioni in BigQuery:

    • bigquery.transfers.update autorizzazioni per creare il trasferimento
    • Autorizzazioni bigquery.datasets.get e bigquery.datasets.update attive il set di dati di destinazione

    Il ruolo IAM predefinito bigquery.admin include bigquery.transfers.update, bigquery.datasets.update e Autorizzazioni bigquery.datasets.get. Per ulteriori informazioni sui ruoli IAM in BigQuery Data Transfer Service, consulta Controllo dell'accesso.

  • Consulta la documentazione di Amazon S3 per assicurarti di avere configurato le autorizzazioni necessarie per abilitare il trasferimento. Come minimo, i dati di origine Amazon S3 devono avere il criterio gestito da AWS AmazonS3ReadOnlyAccess applicato.

Configurare un trasferimento dati Amazon S3

Per creare un trasferimento di dati Amazon S3:

Console

  1. Vai alla pagina BigQuery nella console Google Cloud.

    Vai alla pagina di BigQuery

  2. Fai clic su Trasferimenti.

  3. Fai clic su Crea un trasferimento.

  4. Nella pagina Crea trasferimento:

    • Nella sezione Tipo di origine, per Origine, scegli Amazon S3.

      Origine trasferimento

    • Nella sezione Nome configurazione di trasferimento, per Nome visualizzato, inserisci un nome del trasferimento, ad esempio My Transfer. Il nome del trasferimento può essere qualsiasi valore che consenta di identificare facilmente il trasferimento se necessario per modificarlo in un secondo momento.

      Nome trasferimento

    • Nella sezione Opzioni di pianificazione:

      • Seleziona Frequenza di ripetizione. Se selezioni Ore, Giorni, Settimane o Mesi, devi anche specificare una frequenza. Tu Puoi anche selezionare Personalizzato per creare una ripetizione più specifica frequenza. Se selezioni On demand, questo trasferimento verrà eseguito solo quando il trasferimento viene attivato manualmente.

      • Se applicabile, seleziona Inizia ora o Inizia all'ora impostata. e specificare una data di inizio e un'ora di esecuzione.

    • Nella sezione Impostazioni destinazione, per Set di dati di destinazione, scegli il set di dati creato per archiviare i tuoi dati.

      Trasferisci set di dati

    • Nella sezione Dettagli origine dati:

      • In Tabella di destinazione, inserisci il nome della tabella che hai creato. per archiviare i dati in BigQuery. Nomi tabella di destinazione supportare i parametri.
      • Per URI Amazon S3, inserisci l'URI nel seguente formato s3://mybucket/myfolder/.... Gli URI supportano anche parametri.
      • In ID chiave di accesso, inserisci l'ID della tua chiave di accesso.
      • In Chiave di accesso segreta, inserisci la tua chiave di accesso segreta.
      • In Formato file, scegli il formato dei dati: JSON delimitato da nuova riga, CSV, Avro, Parquet o ORC.

      • Per Disposizione di scrittura, scegli:

        • WRITE_APPEND per aggiungere in modo incrementale nuovi dati al tuo tabella di destinazione esistente. WRITE_APPEND è l'impostazione predefinita per la preferenza di scrittura.
        • WRITE_TRUNCATE per sovrascrivere i dati nella tabella di destinazione. durante ogni esecuzione di trasferimento.

        Per ulteriori informazioni su come BigQuery Data Transfer Service importa i dati utilizzando WRITE_APPEND o WRITE_TRUNCATE, consulta Importazione dati per i trasferimenti Amazon S3. Per ulteriori informazioni sul campo writeDisposition, consulta JobConfigurationLoad.

        Dettagli origine S3

    • Nella sezione Opzioni di trasferimento - tutti i formati:

      • In Numero di errori consentiti, inserisci un valore intero per il numero massimo di record non validi che è possibile ignorare.
      • (Facoltativo) Per i tipi di targeting decimale, inserisci i valori separati da virgole l'elenco dei possibili tipi di dati SQL a cui i valori decimali di origine potrebbero in cui eseguire la conversione. Quale tipo di dati SQL è selezionato per la conversione dipende dalle seguenti condizioni:
        • Il tipo di dati selezionato per la conversione sarà il primo digita il seguente elenco che supporta la precisione e la scalabilità dei dati di origine, nel seguente ordine: NUMERIC, BIGNUMERIC e STRING.
        • Se nessuno dei tipi di dati elencati supporterà la precisione e la scala, il tipo di dati che supporta la più ampia gamma sia selezionato l'elenco specificato. Se un valore supera il limite supportato durante la lettura dei dati di origine, verrà generato un errore.
        • Il tipo di dati STRING supporta tutti i valori di precisione e scala.
        • Se questo campo viene lasciato vuoto, per impostazione predefinita il tipo di dati sarà "NUMERIC,STRING" per ORC e "NUMERIC" per l'altro file formati.
        • Questo campo non può contenere tipi di dati duplicati.
        • L'ordine dei tipi di dati elencati in questo campo viene ignorato.

      Opzioni di trasferimento (tutti i formati)

    • Se hai scelto il formato file CSV o JSON, il file JSON,CSV seleziona Ignora valori sconosciuti per accettare le righe che contengono valori che non corrispondono allo schema. I valori sconosciuti vengono ignorati. Per CSV, questa opzione ignora i valori aggiuntivi alla fine di una riga.

      Ignora valori sconosciuti

    • Se hai scelto CSV come formato file, inserisci uno qualsiasi nella sezione CSV altre opzioni CSV per caricare i dati.

      Opzioni CSV

    • Nel menu Account di servizio, seleziona un account di servizio dagli account di servizio associati progetto Google Cloud. Puoi associare un account di servizio a il trasferimento anziché utilizzare le tue credenziali utente. Per ulteriori informazioni informazioni sull'uso di account di servizio con i trasferimenti di dati, vedi Utilizzare gli account di servizio.

      • Se hai eseguito l'accesso con un'identità federata: per creare un trasferimento è necessario un account di servizio. Se hai firmato con un Account Google, poi l'account di servizio per il trasferimento è facoltativo.
      • L'account di servizio deve disporre delle autorizzazioni richieste.

    • (Facoltativo) Nella sezione Opzioni di notifica:

      • Fai clic sul pulsante di attivazione/disattivazione per abilitare le notifiche via email. Se attivi questa opzione, l'amministratore dei trasferimenti riceve una notifica via email quando un trasferimento non va a buon fine.
      • Per Seleziona un argomento Pub/Sub, scegli l'argomento o fai clic su Crea un argomento per crearne uno. Questa opzione configura l'esecuzione delle notifiche in Pub/Sub per il trasferimento.

  5. Fai clic su Salva.

bq

Inserisci il comando bq mk e fornisci il flag di creazione del trasferimento: --transfer_config.

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'

Dove:

  • project_id: facoltativo. L'ID del tuo progetto Google Cloud. Se --project_id non viene specificato per specificare un particolare progetto, viene utilizzato il progetto predefinito.
  • data_source: campo obbligatorio. Origine dati: amazon_s3.
  • display_name: campo obbligatorio. Il nome visualizzato del trasferimento configurazione. Il nome del trasferimento può essere qualsiasi valore che ti consenta identificare il trasferimento se devi modificarlo in un secondo momento.
  • dataset: campo obbligatorio. Il set di dati di destinazione per la configurazione del trasferimento.
  • service_account: il nome dell'account di servizio utilizzato per di autenticare il trasferimento. L'account di servizio deve essere di proprietà dello stesso project_id usato per creare il trasferimento; devono disporre di tutte le autorizzazioni richieste.

  • parameters: campo obbligatorio. I parametri per il trasferimento creato configurazione in formato JSON. Ad esempio: --params='{"param":"param_value"}'. Di seguito sono riportati i parametri un trasferimento Amazon S3:

    • destination_table_name_template: campo obbligatorio. Il nome del tuo tabella di destinazione.

    • data_path: campo obbligatorio. L'URI Amazon S3, nel seguente formato:

      s3://mybucket/myfolder/...

      Gli URI supportano anche parametri.

    • access_key_id: campo obbligatorio. L'ID della tua chiave di accesso.

    • secret_access_key: campo obbligatorio. La tua chiave di accesso segreta.

    • file_format: facoltativo. Indica il tipo di file che desideri da trasferire: CSV, JSON, AVRO, PARQUET o ORC. Il valore predefinito è CSV.

    • write_disposition: facoltativo. WRITE_APPEND eseguirà il trasferimento solo i file che sono stati modificati dopo la precedente esecuzione riuscita. WRITE_TRUNCATE trasferirà tutti i file corrispondenti, inclusi quelli trasferiti durante un'esecuzione precedente. Il valore predefinito è WRITE_APPEND.

    • max_bad_records: facoltativo. Il numero di errori consentiti record. Il valore predefinito è 0.

    • decimal_target_types: facoltativo. Un elenco separato da virgole di possibili tipi di dati SQL, come i valori decimali di origine in cui viene convertito. Se questo campo non viene fornito, il tipo di dati verrà impostato per impostazione predefinita a "NUMERIC,STRING" per ORC e "NUMERIC" per gli altri formati file.

    • ignore_unknown_values: facoltativo e ignorato se file_format non è JSON o CSV. Indica se ignorare valori sconosciuti nei dati.

    • field_delimiter: facoltativo e si applica solo se file_format è CSV. Il carattere che separa i campi. La il valore predefinito è una virgola.

    • skip_leading_rows: facoltativo e si applica solo se file_format è CSV. Indica il numero di righe di intestazione che non vuoi importare. Il valore predefinito è 0.

    • allow_quoted_newlines: facoltativo e si applica solo se file_format è CSV. Indica se consentire a capo all'interno dei campi tra virgolette.

    • allow_jagged_rows: facoltativo e si applica solo se file_format è CSV. Indica se accettare righe a cui mancano colonne facoltative finali. I valori mancanti verranno i valori NULL.

Ad esempio, il comando seguente crea un trasferimento Amazon S3 denominato My Transfer con un valore data_path pari a s3://mybucket/myfile/*.csv, set di dati di destinazione mydataset e file_format CSV. Questo esempio include valori non predefiniti per i parametri facoltativi associato a CSV file_format.

Il trasferimento viene creato nel progetto predefinito:

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

Dopo aver eseguito il comando, viene visualizzato un messaggio simile al seguente:

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

Segui le istruzioni e incolla il codice di autenticazione nel comando dalla riga di comando.

API

Utilizza la projects.locations.transferConfigs.create e fornisce un'istanza del metodo TransferConfig risorsa.

Java

Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client. 

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());
    }
  }
}

Impatto della corrispondenza dei prefissi e delle corrispondenze con caratteri jolly

L'API Amazon S3 supporta la corrispondenza dei prefissi, ma non quelli dei caratteri jolly. Tutti I file Amazon S3 che corrispondono a un prefisso verranno trasferiti in Google Cloud. Tuttavia, solo quelli che corrispondono all'URI Amazon S3 nella configurazione del trasferimento verrà effettivamente caricato in BigQuery. Ciò potrebbe comportare i costi in eccesso per il trasferimento di dati in uscita da Amazon S3 per i file trasferiti, non caricato in BigQuery.

Considera ad esempio questo percorso dati:

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

Insieme a questi file nella posizione di origine:

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

In questo modo, tutti i file Amazon S3 con prefisso s3://bucket/folder/ in fase di trasferimento a Google Cloud. In questo esempio, sia file1.csv che L'importo di file2.csv verrà trasferito.

Tuttavia, solo i file corrispondenti a s3://bucket/folder/*/subfolder/*.csv in BigQuery. In questo esempio, solo file1.csv verrà caricato in BigQuery.

Risolvere i problemi di configurazione del trasferimento

In caso di problemi durante la configurazione del trasferimento, consulta l'articolo Problemi di trasferimento con Amazon S3.

Passaggi successivi