Trasferimenti dell'archiviazione BLOB

BigQuery Data Transfer Service per Archiviazione BLOB di Azure consente di pianificare e gestire automaticamente i job di caricamento ricorrenti dall'archiviazione BLOB a BigQuery.

Prima di iniziare

Prima di creare un trasferimento nello spazio di archiviazione BLOB, segui questi passaggi:

Autorizzazioni obbligatorie

Per creare un trasferimento nello spazio di archiviazione BLOB, devi disporre dell'autorizzazione bigquery.transfers.update Identity and Access Management (IAM). Devi anche avere le autorizzazioni bigquery.datasets.get e bigquery.datasets.update per il set di dati di destinazione.

Il ruolo IAM bigquery.admin predefinito include le autorizzazioni necessarie per creare un trasferimento nell'archiviazione BLOB.

Per maggiori informazioni su BigQuery IAM, consulta Controllo dell'accesso con IAM.

Per verificare di avere le autorizzazioni corrette in Archiviazione BLOB per abilitare il trasferimento, consulta Firma di accesso condiviso (SAS).

Se intendi configurare le notifiche di esecuzione del trasferimento per Pub/Sub, devi avere l'autorizzazione pubsub.topics.setIamPolicy. Le autorizzazioni Pub/Sub non sono necessarie solo per le notifiche via email. Per ulteriori informazioni, consulta Notifiche di esecuzione di BigQuery Data Transfer Service.

Limitazioni

I trasferimenti dell'archiviazione BLOB sono soggetti alle seguenti limitazioni:

Configura un trasferimento di dati per l'archiviazione BLOB

Seleziona una delle seguenti opzioni:

Console

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nel menu di navigazione di BigQuery, fai clic su Trasferimenti di dati.

  3. Fai clic su Crea trasferimento.

  4. Nella pagina Crea trasferimento, procedi nel seguente modo:

    • Nella sezione Tipo di origine, per Origine, scegli Archiviazione BLOB di Azure.

      Tipo di origine trasferimento

    • Nella sezione Nome configurazione di trasferimento, in Nome visualizzato, inserisci un nome per il trasferimento.

    • Nella sezione Opzioni di pianificazione:

      • Seleziona una Frequenza di ripetizione. Se selezioni Ore, Giorni, Settimane o Mesi, devi specificare anche una frequenza. Puoi anche selezionare Personalizzato per specificare una frequenza di ripetizione personalizzata. Se selezioni On demand, questo trasferimento viene eseguito quando attivi manualmente il trasferimento.

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

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

    • Nella sezione Dettagli origine dati, procedi nel seguente modo:

      • In Tabella di destinazione, inserisci il nome della tabella creata per archiviare i dati in BigQuery. I nomi delle tabelle di destinazione supportano i parametri.
      • In Nome account Archiviazione Azure, inserisci il nome dell'account Archiviazione BLOB.
      • In Nome container, inserisci il nome del container Archiviazione BLOB.
      • In Percorso dati, inserisci il percorso per filtrare i file da trasferire. Vedi esempi.
      • In Token SAS, inserisci il token SAS di Azure.
      • In Formato file, scegli il formato dei dati di origine.
      • Per Disposizione di scrittura, seleziona WRITE_APPEND per aggiungere in modo incrementale nuovi dati alla tabella di destinazione oppure WRITE_TRUNCATE per sovrascrivere i dati nella tabella di destinazione durante ogni esecuzione di trasferimento. WRITE_APPEND è il valore predefinito per Disposizione di scrittura.

      Per maggiori informazioni su come BigQuery Data Transfer Service importa i dati utilizzando WRITE_APPEND o WRITE_TRUNCATE, consulta Importazione dati per i trasferimenti BLOB di Azure. Per maggiori informazioni sul campo writeDisposition, consulta JobConfigurationLoad.

      Dettagli origine dati

    • Nella sezione Opzioni di trasferimento, procedi nel seguente modo:

      • In Numero di errori consentiti, inserisci un valore intero relativo al numero massimo di record non validi che possono essere ignorati. Il valore predefinito è 0.
      • (Facoltativo) In Tipi di destinazione decimali, inserisci un elenco separato da virgole dei possibili tipi di dati SQL in cui vengono convertiti i valori decimali nei dati di origine. Il tipo di dati SQL selezionato per la conversione dipende dalle seguenti condizioni:
        • Nell'ordine NUMERIC, BIGNUMERIC e STRING, un tipo viene selezionato se è nell'elenco specificato e se supporta la precisione e la scala.
        • Se nessuno dei tipi di dati elencati supporta la precisione e la scalabilità, viene selezionato il tipo di dati che supporta l'intervallo più ampio nell'elenco specificato. Se durante la lettura dei dati di origine un valore supera l'intervallo supportato, viene visualizzato 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 altri formati file.
        • Questo campo non può contenere tipi di dati duplicati.
        • L'ordine dei tipi di dati elencati viene ignorato.

    • Se hai scelto CSV o JSON come formato file, nella sezione JSON, CSV seleziona Ignora valori sconosciuti per accettare le righe che contengono valori che non corrispondono allo schema.

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

      Opzioni CSV

    • Nella sezione Opzioni di notifica, puoi scegliere di abilitare le notifiche via email e le notifiche Pub/Sub.

      • Quando abiliti le notifiche via email, l'amministratore dei trasferimenti riceve una notifica via email quando un'esecuzione del trasferimento non va a buon fine.
      • Quando abiliti le notifiche Pub/Sub, scegli un nome per l'argomento in cui pubblicare o fai clic su Crea un argomento per crearne uno.

    • Se utilizzi CMEK, nella sezione Opzioni avanzate, seleziona Chiave gestita dal cliente. Viene visualizzato un elenco di CMEK disponibili. Per informazioni su come funzionano le CMEK con BigQuery Data Transfer Service, vedi Specificare la chiave di crittografia con i trasferimenti.

  5. Fai clic su Salva.

bq

Utilizza il comando bq mk --transfer_config per creare un trasferimento nell'archiviazione BLOB:

bq mk \
  --transfer_config \
  --project_id=PROJECT_ID \
  --data_source=DATA_SOURCE \
  --display_name=DISPLAY_NAME \
  --target_dataset=DATASET \
  --destination_kms_key=DESTINATION_KEY \
  --params=PARAMETERS

Sostituisci quanto segue:

  • PROJECT_ID: (facoltativo) l'ID progetto contenente il set di dati di destinazione. Se non specificato, viene utilizzato il tuo progetto predefinito.
  • DATA_SOURCE: azure_blob_storage.
  • DISPLAY_NAME: il nome visualizzato per la configurazione di trasferimento. Il nome del trasferimento può essere qualsiasi valore che ti consenta di identificare facilmente il trasferimento se devi modificarlo in seguito.
  • DATASET: il set di dati di destinazione per la configurazione del trasferimento.
  • DESTINATION_KEY: (facoltativo) l'ID risorsa della chiave Cloud KMS, ad esempio projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
  • PARAMETERS: i parametri per la configurazione del trasferimento, elencati in formato JSON. Ad esempio, --params={"param1":"value1", "param2":"value2"}. Di seguito sono riportati i parametri per un trasferimento nell'archiviazione BLOB:
    • destination_table_name_template: obbligatorio. Il nome della tabella di destinazione.
    • storage_account: obbligatorio. Il nome dell'account Archiviazione BLOB.
    • container: obbligatorio. Il nome del container di archiviazione BLOB.
    • data_path: facoltativo. Il percorso per filtrare i file da trasferire. Visualizza alcuni esempi.
    • sas_token: obbligatorio. Il token SAS di Azure.
    • file_format: facoltativo. Tipo di file che vuoi trasferire: CSV, JSON, AVRO, PARQUET o ORC. Il valore predefinito è CSV.
    • write_disposition: facoltativo. Seleziona WRITE_APPEND per aggiungere dati alla tabella di destinazione oppure WRITE_TRUNCATE per sovrascrivere i dati nella tabella di destinazione. Il valore predefinito è WRITE_APPEND.
    • max_bad_records: facoltativo. Il numero di record errati consentiti. Il valore predefinito è 0.
    • decimal_target_types: facoltativo. Un elenco separato da virgole di possibili tipi di dati SQL in cui vengono convertiti i valori decimali nei dati di origine. Se questo campo non viene fornito, il tipo di dati predefinito sarà NUMERIC,STRING per ORC e NUMERIC per gli altri formati file.
    • ignore_unknown_values: facoltativo e ignorato se file_format non è JSON o CSV. Imposta su true per accettare righe che contengono valori che non corrispondono allo schema.
    • field_delimiter: facoltativo e si applica solo quando file_format è CSV. Il carattere che separa i campi. Il valore predefinito è ,.
    • skip_leading_rows: facoltativo e si applica solo quando file_format è CSV. Indica il numero di righe di intestazione che non desideri importare. Il valore predefinito è 0.
    • allow_quoted_newlines: facoltativo e si applica solo quando file_format è CSV. Indica se consentire l'inserimento di ritorni a capo nei campi tra virgolette.
    • allow_jagged_rows: facoltativo e si applica solo quando file_format è CSV. Indica se accettare le righe prive di colonne finali facoltative. I valori mancanti sono compilati con NULL.

Ad esempio, quanto segue crea un trasferimento nell'archiviazione BLOB denominato mytransfer:

bq mk \
  --transfer_config \
  --data_source=azure_blob_storage \
  --display_name=mytransfer \
  --target_dataset=mydataset \
  --destination_kms_key=projects/myproject/locations/us/keyRings/mykeyring/cryptoKeys/key1
  --params={"destination_table_name_template":"mytable",
      "storage_account":"myaccount",
      "container":"mycontainer",
      "data_path":"myfolder/*.csv",
      "sas_token":"my_sas_token_value",
      "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"}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 azure blob storage transfer config.
public class CreateAzureBlobStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String displayName = "MY_TRANSFER_DISPLAY_NAME";
    final String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    String storageAccount = "MY_AZURE_STORAGE_ACCOUNT_NAME";
    String containerName = "MY_AZURE_CONTAINER_NAME";
    String dataPath = "MY_AZURE_FILE_NAME_OR_PREFIX";
    String sasToken = "MY_AZURE_SAS_TOKEN";
    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("storage_account", Value.newBuilder().setStringValue(storageAccount).build());
    params.put("container", Value.newBuilder().setStringValue(containerName).build());
    params.put("data_path", Value.newBuilder().setStringValue(dataPath).build());
    params.put("sas_token", Value.newBuilder().setStringValue(sasToken).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());
    createAzureBlobStorageTransfer(projectId, displayName, datasetId, params);
  }

  public static void createAzureBlobStorageTransfer(
      String projectId, String displayName, String datasetId, Map<String, Value> params)
      throws IOException {
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName(displayName)
            .setDataSourceId("azure_blob_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    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("Azure Blob Storage transfer created successfully: " + config.getName());
    } catch (ApiException ex) {
      System.out.print("Azure Blob Storage transfer was not created." + ex.toString());
    }
  }
}

Specifica la chiave di crittografia con i trasferimenti

Puoi specificare chiavi di crittografia gestite dal cliente (CMEK) per criptare i dati per un'esecuzione di trasferimento. Puoi utilizzare una CMEK per supportare i trasferimenti dall'archiviazione BLOB di Azure.

Quando specifichi una CMEK con un trasferimento, BigQuery Data Transfer Service applica la CMEK a qualsiasi cache su disco intermedia di dati importati, in modo che l'intero flusso di lavoro di trasferimento dei dati sia conforme a CMEK.

Non puoi aggiornare un trasferimento esistente per aggiungere una CMEK se il trasferimento non è stato creato originariamente con una CMEK. Ad esempio, non puoi modificare una tabella di destinazione che in origine era criptata per impostazione predefinita per ora essere criptata con CMEK. Al contrario, non puoi modificare una tabella di destinazione criptata con CMEK in modo che abbia un tipo di crittografia diverso.

Puoi aggiornare una CMEK per un trasferimento se la configurazione di trasferimento è stata creata originariamente con una crittografia CMEK. Quando aggiorni una CMEK per una configurazione di trasferimento, BigQuery Data Transfer Service propaga la CMEK alle tabelle di destinazione all'esecuzione successiva del trasferimento, in cui BigQuery Data Transfer Service sostituisce eventuali CMEK obsolete con la nuova CMEK durante l'esecuzione del trasferimento. Per ulteriori informazioni, vedi Aggiornare un trasferimento.

Puoi anche utilizzare le chiavi predefinite del progetto. Quando specifichi una chiave predefinita del progetto con un trasferimento, BigQuery Data Transfer Service utilizza la chiave predefinita del progetto come chiave predefinita per qualsiasi nuova configurazione di trasferimento.

Risolvere i problemi di configurazione del trasferimento

Se hai problemi durante la configurazione del trasferimento, consulta Problemi di trasferimento dell'archiviazione BLOB.

Passaggi successivi