Trasferimenti di Amazon S3

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

Prima di iniziare

Prima di creare un trasferimento di dati Amazon S3:

Limitazioni

I trasferimenti di dati di Amazon S3 sono soggetti alle seguenti limitazioni:

  • La parte del bucket dell'URI Amazon S3 non può essere parametrizzata.
  • I trasferimenti di dati da Amazon S3 con il parametro Write disposition impostato su WRITE_TRUNCATE trasferiranno tutti i file corrispondenti a Google Cloud durante ogni esecuzione. Ciò potrebbe comportare costi aggiuntivi per il trasferimento dei dati in uscita da Amazon S3. Per maggiori informazioni sui file trasferiti durante un'esecuzione, consulta Impatto della corrispondenza del prefisso rispetto alla corrispondenza con caratteri jolly.
  • I trasferimenti di dati dalle regioni AWS GovCloud (us-gov) non sono supportati.
  • I trasferimenti di dati alle località BigQuery Omni non sono supportati.

  • A seconda del formato dei dati di origine Amazon S3, potrebbero esserci limitazioni aggiuntive. Per ulteriori informazioni, vedi:

  • L'intervallo di tempo minimo tra i trasferimenti di dati ricorrenti è di 24 ore. L'intervallo predefinito per un trasferimento dati ricorrente è di 24 ore.

Autorizzazioni obbligatorie

Prima di creare un trasferimento di dati Amazon S3:

  • Assicurati che la persona che crea il trasferimento di dati disponga delle seguenti autorizzazioni obbligatorie in BigQuery:

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

    Il ruolo IAM predefinito bigquery.admin include le autorizzazioni bigquery.transfers.update, bigquery.datasets.update e bigquery.datasets.get. Per saperne di più sui ruoli IAM in BigQuery Data Transfer Service, consulta Controllo dell'accesso.

  • Consulta la documentazione di Amazon S3 per assicurarti di aver configurato tutte le autorizzazioni necessarie per abilitare il trasferimento dei dati. Come minimo, ai dati dell'origine Amazon S3 deve essere applicato il criterio gestito AWS AmazonS3ReadOnlyAccess.

Configurare un trasferimento di dati Amazon S3

Per creare un trasferimento di dati Amazon S3:

Console

  1. Vai alla pagina Trasferimenti dati nella console Google Cloud.

    Vai a Trasferimenti dati

  2. Fai clic su Crea trasferimento.

  3. Nella pagina Crea trasferimento:

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

      Origine trasferimento

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

      Nome trasferimento

    • Nella sezione Opzioni di programmazione:

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

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

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

      Trasferisci set di dati

    • Nella sezione Dettagli dell'origine dati:

      • In Tabella di destinazione, inserisci il nome della tabella che hai creato per archiviare i dati in BigQuery. I nomi delle tabelle di destinazione supportano 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 chiave di accesso.
      • In Chiave di accesso segreta, inserisci la tua chiave di accesso segreta.
      • Per Formato file, scegli il formato dei dati: JSON delimitato da nuova riga, CSV, Avro, Parquet o ORC.

      • Per Write Disposition (Disposizione scrittura), scegli:

        • WRITE_APPEND per accodare in modo incrementale i nuovi dati alla tabella di destinazione esistente. WRITE_APPEND è il valore predefinito per la preferenza di scrittura.
        • WRITE_TRUNCATE per sovrascrivere i dati nella tabella di destinazione durante ogni esecuzione del trasferimento dati.

        Per saperne di più 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 dell'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 errati che possono essere ignorati.
      • (Facoltativo) Per Tipi di destinazione decimali, inserisci un elenco separato da virgole di possibili tipi di dati SQL in cui possono essere convertiti i valori decimali di origine. Il tipo di dati SQL selezionato per la conversione dipende dalle seguenti condizioni:
        • Il tipo di dati selezionato per la conversione sarà il primo nel seguente elenco che supporta la precisione e la scala dei dati di origine, in questo ordine: NUMERIC, BIGNUMERIC e STRING.
        • Se nessuno dei tipi di dati elencati supporta la precisione e la scala, viene selezionato il tipo di dati che supporta l'intervallo più ampio nell'elenco specificato. Se un valore supera l'intervallo 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, il tipo di dati predefinito sarà "NUMERIC,STRING" per ORC e "NUMERIC" per gli altri formati file.
        • Questo campo non può contenere tipi di dati duplicati.
        • L'ordine dei tipi di dati elencati in questo campo viene ignorato.

      Opzioni di trasferimento per tutti i formati

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

      Ignora valori sconosciuti

    • Se hai scelto CSV come formato file, nella sezione CSV inserisci eventuali opzioni CSV aggiuntive per il caricamento dei dati.

      Opzioni CSV

    • Nel menu Account di servizio, seleziona un account di servizio tra quelli associati al tuo progetto Google Cloud. Puoi associare un account di servizio al trasferimento dei dati anziché utilizzare le credenziali utente. Per ulteriori informazioni sull'utilizzo degli account di servizio con i trasferimenti di dati, consulta Utilizzare gli account di servizio.

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

    • (Facoltativo) Nella sezione Opzioni di notifica:

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

  4. Fai clic su Salva.

bq

Inserisci il comando bq mk e specifica 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 non viene fornito --project_id per specificare un determinato progetto, viene utilizzato il progetto predefinito.
  • data_source: obbligatorio. L'origine dati: amazon_s3.
  • display_name: obbligatorio. Il nome visualizzato per la configurazione del trasferimento di dati. Il nome del trasferimento può essere qualsiasi valore che ti consenta di identificare il trasferimento se devi modificarlo in un secondo momento.
  • dataset: obbligatorio. Il set di dati di destinazione per la configurazione del trasferimento dati.
  • service_account: il nome account di servizio utilizzato per autenticare il trasferimento dei dati. L'account di servizio deve essere di proprietà dello stesso project_id utilizzato per creare il trasferimento dei dati e deve disporre di tutte le autorizzazioni richieste.

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

    • destination_table_name_template: obbligatorio. Il nome della tabella di destinazione.

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

      s3://mybucket/myfolder/...

      Gli URI supportano anche parametri.

    • access_key_id: obbligatorio. Il tuo ID chiave di accesso.

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

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

    • write_disposition: facoltativo. WRITE_APPEND trasferirà solo i file che sono stati modificati dall'ultima esecuzione riuscita. WRITE_TRUNCATE trasferirà tutti i file corrispondenti, inclusi quelli trasferiti in un'esecuzione precedente. Il valore predefinito è WRITE_APPEND.

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

    • decimal_target_types: facoltativo. Un elenco separato da virgole di possibili tipi di dati SQL in cui è possibile convertire i valori decimali di origine. Se questo campo non viene fornito, il tipo di dato predefinito è "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 i valori sconosciuti nei dati.

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

    • skip_leading_rows: facoltativo e si applica solo quando 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 quando file_format è CSV. Indica se consentire i caratteri di fine riga all'interno dei campi tra virgolette.

    • allow_jagged_rows: facoltativo e si applica solo quando file_format è CSV. Indica se accettare le righe che non hanno le colonne finali facoltative. I valori mancanti verranno completati con valori NULL.

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

Il trasferimento dei dati 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 sulla riga di comando.

API

Utilizza il metodo projects.locations.transferConfigs.create e fornisci un'istanza della risorsa TransferConfig.

Java

Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare 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 del prefisso rispetto alla corrispondenza con caratteri jolly

L'API Amazon S3 supporta la ricerca di corrispondenze tramite prefisso, ma non la ricerca di corrispondenze tramite caratteri jolly. Tutti i file Amazon S3 corrispondenti a un prefisso verranno trasferiti in Google Cloud. Tuttavia, solo quelli che corrispondono all'URI di Amazon S3 nella configurazione del trasferimento verranno effettivamente caricati in BigQuery. Ciò potrebbe comportare costi eccessivi per il trasferimento dei dati in uscita da Amazon S3 per i file trasferiti, ma non caricati in BigQuery.

Ad esempio, considera questo percorso dei dati:

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

Oltre a questi file nella posizione di origine:

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

Di conseguenza, tutti i file Amazon S3 con il prefisso s3://bucket/folder/ verranno trasferiti a Google Cloud. In questo esempio, verranno trasferiti sia file1.csv sia file2.csv.

Tuttavia, solo i file corrispondenti a s3://bucket/folder/*/subfolder/*.csv verranno caricati effettivamente in BigQuery. In questo esempio, solo file1.csv viene caricato in BigQuery.

Risolvere i problemi di configurazione del trasferimento

Se hai problemi a configurare il trasferimento dei dati, consulta Problemi di trasferimento di Amazon S3.

Passaggi successivi