Caricare i dati di Salesforce in BigQuery

Puoi caricare i dati dal tuo account Salesforce Sales a BigQuery utilizzando il connettore BigQuery Data Transfer Service per Salesforce. Con BigQuery Data Transfer Service, puoi pianificare job di trasferimento ricorrenti che aggiungono i dati più recenti dal tuo account vendite Salesforce a BigQuery.

Limitazioni

I trasferimenti di dati Salesforce sono soggetti alle seguenti limitazioni:

  • Il connettore Salesforce supporta solo i trasferimenti da un account Salesforce Sales.
  • Il connettore Salesforce supporta solo i campi inclusi nella versione 64.0 dell'API Bulk di Salesforce. Alcuni campi inclusi nelle versioni precedenti dell'API Salesforce Bulk potrebbero non essere supportati. Per saperne di più su queste modifiche al connettore Salesforce, consulta API collettiva Salesforce.
  • Il connettore Salesforce utilizza l'API Salesforce Bulk V1 per connettersi all'endpoint Salesforce per recuperare i dati.
    • Il connettore Salesforce supporta solo l'API Salesforce Bulk V1 per connettersi all'istanza Salesforce e solo il trasferimento di entità supportate dall'API Salesforce Bulk. Per saperne di più sulle entità supportate, consulta Errore "L'entità non è supportata dall'API Bulk".
  • Il connettore Salesforce non supporta il trasferimento dei seguenti oggetti con campi binari.
    • Attachment
    • ContentVersion
    • Document
    • StaticResource
    • Scontrol
    • EmailCapture
    • MailMergeTemplate
  • L'intervallo di tempo minimo tra i trasferimenti di dati ricorrenti è di 15 minuti. L'intervallo predefinito per un trasferimento ricorrente è di 24 ore.
  • A causa dei limiti di elaborazione di Salesforce, la pianificazione di troppi trasferimenti di dati contemporaneamente può causare ritardi o errori. Ti consigliamo di limitare i trasferimenti di dati Salesforce a quanto segue:
    • Non avere più di 10 asset per configurazione di trasferimento.
    • Nelle diverse configurazioni di trasferimento, non eseguire più di 10 trasferimenti simultanei alla volta.
  • Una singola configurazione di trasferimento può supportare una sola esecuzione di trasferimento dei dati in un determinato momento. Nel caso in cui sia pianificato l'esecuzione di un secondo trasferimento di dati prima del completamento del primo, solo il primo trasferimento di dati viene completato, mentre gli altri trasferimenti di dati che si sovrappongono al primo vengono ignorati.
    • Per evitare trasferimenti ignorati all'interno di una singola configurazione di trasferimento, ti consigliamo di aumentare la durata di tempo tra i trasferimenti di grandi quantità di dati configurando la Frequenza di ripetizione.
  • Se l'interfaccia di rete configurata e l'istanza di macchina virtuale (VM) si trovano in regioni diverse, potrebbe verificarsi uno spostamento dei dati tra regioni quando trasferisci i dati da Salesforce.

Limitazioni del trasferimento incrementale

I trasferimenti incrementali da Salesforce sono soggetti alle seguenti limitazioni:

  • Puoi scegliere solo TIMESTAMP colonne come colonne filigrana.
  • L'importazione incrementale è supportata solo per gli asset con colonne della filigrana valide.
  • I valori in una colonna filigrana devono aumentare in modo monotono.
  • I trasferimenti incrementali non possono sincronizzare le operazioni di eliminazione nella tabella di origine.
  • Una singola configurazione di trasferimento può supportare solo l'importazione incrementale o completa.
  • Non puoi aggiornare gli oggetti nell'elenco asset dopo la prima esecuzione dell'importazione incrementale.
  • Non puoi modificare la modalità di scrittura in una configurazione di trasferimento dopo la prima esecuzione dell'importazione incrementale.
  • Non puoi modificare la colonna della filigrana o la chiave primaria dopo la prima esecuzione dell'importazione incrementale.

Opzioni di importazione dei dati

Le sezioni seguenti forniscono ulteriori informazioni sulle opzioni di importazione dati quando configuri un trasferimento di dati Salesforce.

Trasferimenti completi o incrementali

Puoi specificare come caricare i dati in BigQuery selezionando la preferenza di scrittura Completa o Incrementale nella configurazione del trasferimento quando configuri un trasferimento Salesforce. I trasferimenti incrementali sono supportati in anteprima.

Puoi selezionare Completo per trasferire tutti i dati dai tuoi set di dati Salesforce a ogni trasferimento di dati.

In alternativa, puoi selezionare Incrementale (Anteprima) per trasferire solo i dati modificati dall'ultimo trasferimento, anziché caricare l'intero set di dati a ogni trasferimento. Se selezioni Incrementale per il trasferimento dei dati, devi specificare le modalità di scrittura Accoda o Upsert per definire come vengono scritti i dati in BigQuery durante un trasferimento incrementale dei dati. Le sezioni seguenti descrivono le modalità di scrittura disponibili.

Modalità di scrittura Aggiungi

La modalità di scrittura Aggiungi inserisce solo nuove righe nella tabella di destinazione. Questa opzione aggiunge rigorosamente i dati trasferiti senza verificare la presenza di record esistenti, pertanto questa modalità può potenzialmente causare la duplicazione dei dati nella tabella di destinazione.

Quando selezioni la modalità Aggiungi, devi selezionare una colonna della filigrana. Per consentire al connettore Salesforce di monitorare le modifiche nella tabella di origine, è necessaria una colonna filigrana.

Per i trasferimenti Salesforce, ti consigliamo di selezionare una colonna che viene aggiornata solo quando è stato creato il record e non cambia con gli aggiornamenti successivi. Ad esempio, la colonna CreatedDate.

Modalità di scrittura Upsert

La modalità di scrittura Upsert aggiorna una riga o ne inserisce una nuova nella tabella di destinazione controllando una chiave primaria. Puoi specificare una chiave primaria per consentire al connettore Salesforce di determinare le modifiche necessarie per mantenere la tabella di destinazione aggiornata con la tabella di origine. Se la chiave primaria specificata è presente nella tabella BigQuery di destinazione durante un trasferimento di dati, il connettore Salesforce aggiorna la riga con i nuovi dati della tabella di origine. Se una chiave primaria non è presente durante un trasferimento di dati, il connettore Salesforce inserisce una nuova riga.

Quando selezioni la modalità Upsert, devi selezionare una colonna filigrana e una chiave primaria:

  • Per consentire al connettore Salesforce di monitorare le modifiche nella tabella di origine, è necessaria una colonna filigrana.
    • Seleziona una colonna filigrana che si aggiorna ogni volta che una riga viene modificata. Ti consigliamo di utilizzare la colonna SystemModstamp o LastModifiedDate.
  • La chiave primaria può essere una o più colonne della tabella necessarie per il connettore Salesforce per determinare se deve inserire o aggiornare una riga.
    • Seleziona le colonne che contengono valori non nulli univoci in tutte le righe della tabella. Ti consigliamo colonne che includano identificatori generati dal sistema, codici di riferimento univoci (ad esempio ID a incremento automatico) o ID sequenza basati sul tempo immutabili.
    • Per evitare potenziali perdite o danneggiamenti dei dati, le colonne della chiave primaria che selezioni devono avere valori univoci. Se hai dubbi sull'unicità della colonna della chiave primaria che hai scelto, ti consigliamo di utilizzare la modalità di scrittura Aggiungi.

Prima di iniziare

Le sezioni seguenti descrivono i passaggi da seguire prima di creare un trasferimento di dati Salesforce.

Crea un'app connessa a Salesforce

Devi creare un'app connessa Salesforce con le seguenti configurazioni richieste:

  • Configura le informazioni di base nell'app connessa. I campi Nome app connessa ed Email di contatto sono obbligatori per un trasferimento Salesforce.
  • Enable OAuth Settings (Abilita impostazioni OAuth) con le seguenti configurazioni:
    • Seleziona la casella di controllo Abilita impostazioni OAuth.
    • Nel campo Callback URL (URL di callback), inserisci quanto segue:
      • Per un ambiente di produzione, inserisci https://login.salesforce.com/services/oauth2/token.
      • Per un ambiente sandbox, inserisci https://test.salesforce.com/services/oauth2/token.
    • Verifica che la casella di controllo Emetti token di accesso basati su JWT(JSON Web Token) per utenti denominati non sia selezionata.
  • Nella sezione Selected OAuth Scopes (Ambiti OAuth selezionati), seleziona Manage user data via APIs (api) (Gestisci dati utente tramite API (api)).
  • Deseleziona la casella di controllo Required Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows (Estensione Proof Key for Code Exchange (PKCE) obbligatoria per i flussi di autorizzazione supportati).
  • Seleziona Enable Client Credentials Flow (Abilita flusso delle credenziali client), quindi fai clic su Ok nell'avviso visualizzato.

Dopo aver configurato l'app collegata con le configurazioni richieste, fai clic su Salva. Viene visualizzata la pagina dei dettagli dell'app connessa appena creata.

Dopo aver creato l'app connessa, devi anche configurare il flusso delle credenziali client nel seguente modo:

  1. Fai clic su Configurazione.
  2. Nella barra di ricerca, cerca App collegate.
  3. Fai clic su Gestisci app > App collegate. Se utilizzi Salesforce Lightning Experience, fai clic su Gestisci app connesse.
  4. Nell'app connessa che hai creato, fai clic su Modifica.
  5. Viene visualizzata la pagina Dettagli app. Nella sezione Client Credentials Flow (Flusso di credenziali client), inserisci il tuo nome utente nel campo Esegui come. Puoi utilizzare lo strumento di ricerca in questo campo per assicurarti di aver selezionato l'utente corretto.
  6. Fai clic su Salva.

Informazioni Salesforce richieste

Quando crei un trasferimento di dati Salesforce, devi disporre delle seguenti informazioni di Salesforce:

Nome parametro Descrizione
myDomain Il tuo Il mio dominio in Salesforce.
clientId Chiave utente dell'applicazione collegata a Salesforce.
clientSecret

Client secret OAuth o secret consumer dell'applicazione collegata a Salesforce.

Per ottenere i valori di myDomain, clientID e clientSecret, seleziona una delle seguenti opzioni:

Salesforce Classic

Recuperare i dettagli di myDomain

Per trovare il tuo myDomain:

  1. Accedi alla piattaforma Salesforce.
  2. Fai clic su Configurazione.
  3. Nella barra di ricerca, cerca Il mio dominio.
  4. Nei risultati di ricerca, fai clic su Domain Management (Gestione dominio) > My Domain (Il mio dominio).

Nella sezione Dettagli del mio dominio, il tuo myDomain viene visualizzato come prefisso nell'URL corrente di My Domain. Ad esempio, se l'URL di My Domain è example.my.salesforce.com, il valore myDomain da utilizzare è example.

Recupera i dettagli di ClientId e ClientSecret

Per trovare i valori di ClientId e ClientSecret:

  1. Accedi alla piattaforma Salesforce.
  2. Fai clic su Configurazione.
  3. Nella barra di ricerca, cerca App.
  4. Nella sezione Crea dei risultati di ricerca, fai clic su Crea > App.
  5. Fai clic su un nome di app collegata.
  6. Nella pagina dei dettagli App collegate, fai clic su Gestisci i dettagli del consumatore.
  7. Verifica la tua identità utilizzando uno dei metodi registrati. Puoi visualizzare la pagina dei dettagli del consumatore per un massimo di cinque minuti prima che ti venga chiesto di verificare di nuovo la tua identità.
  8. Nella pagina Dettagli utente, la Consumer Key è il valore di ClientId. Il Customer Secret è il valore di ClientSecret.

Salesforce Lightning Experience

Recuperare i dettagli di myDomain

Per trovare il tuo myDomain:

  1. Accedi alla piattaforma Salesforce.
  2. Fai clic su Configurazione.

Apri la pagina di configurazione nella piattaforma Salesforce.

  1. Nella barra di ricerca, cerca Il mio dominio.
  2. Nei risultati di ricerca, fai clic su Impostazioni azienda > Il mio dominio.

Nella sezione Dettagli del mio dominio, il tuo myDomain viene visualizzato come prefisso nell'URL corrente di My Domain. Ad esempio, se l'URL di My Domain è example.my.salesforce.com, il valore myDomain da utilizzare è example.

Recuperare i dettagli di ClientId e ClientSecret

  1. Accedi alla piattaforma Salesforce.
  2. Fai clic su Configurazione.
  3. Nella barra di ricerca, cerca App.
  4. Nei risultati di ricerca, fai clic su App > Gestione app.
  5. Trova un'app collegata e fai clic su Visualizza.
  6. Fai clic su Gestisci i dettagli del consumer.
  7. Verifica la tua identità utilizzando uno dei metodi registrati. Puoi visualizzare la pagina dei dettagli del consumatore per un massimo di cinque minuti prima che ti venga chiesto di verificare di nuovo la tua identità.
  8. Nella pagina Dettagli utente, la Consumer Key è il valore di ClientId. Il Customer Secret è il valore di ClientSecret.

Configura la lista consentita IP per i trasferimenti Salesforce

Devi configurare il tuo Google Cloud ambiente e il tuo account Salesforce per aggiungere indirizzi IP specifici alla lista consentita per i trasferimenti di dati. In questo modo, Salesforce accetta solo connessioni da un indirizzo IP statico attendibile.

Per farlo, devi prima configurare la tua rete Google Cloud in modo che utilizzi un indirizzo IP statico:

  1. Configura una Network Address Translation (NAT) pubblica con un indirizzo IP statico all'interno della tua rete Virtual Private Cloud. Cloud NAT deve essere configurato nella stessa regione del set di dati di destinazione per questo trasferimento di dati.
  2. Configura un collegamento di rete all'interno della stessa rete VPC. Questa risorsa viene utilizzata da BigQuery Data Transfer Service per accedere ai servizi privati.

Successivamente, devi configurare gli intervalli IP attendibili in Salesforce. Quando aggiungi l'intervallo di indirizzi IP, utilizza l'indirizzo IP statico del tuo Google Cloud NAT pubblico sia per l'indirizzo IP iniziale che per quello finale dell'intervallo IP.

Una volta configurati gli intervalli IP, puoi specificare l'IP statico quando configuri il trasferimento selezionando l'allegato di rete nel campo Allegato di rete.

Prerequisiti di BigQuery

Ruoli BigQuery richiesti

Per ottenere le autorizzazioni necessarie per creare un trasferimento di dati BigQuery Data Transfer Service, chiedi all'amministratore di concederti il ruolo IAM Amministratore BigQuery (roles/bigquery.admin) nel tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare un trasferimento di dati BigQuery Data Transfer Service. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare un trasferimento di dati di BigQuery Data Transfer Service sono necessarie le seguenti autorizzazioni:

  • Autorizzazioni BigQuery Data Transfer Service:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • Autorizzazioni BigQuery:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Per maggiori informazioni, vedi Concedere l'accesso a bigquery.admin.

Configura un trasferimento di dati Salesforce

Aggiungi i dati di Salesforce a BigQuery configurando una configurazione del trasferimento utilizzando una delle seguenti opzioni:

Console

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

    Vai a Trasferimenti dati

  2. Fai clic su Crea trasferimento.

  3. Nella sezione Tipo di origine, per Origine, scegli Salesforce.

  4. Nella sezione Dettagli origine dati, segui questi passaggi:

    • Per Collegamento di rete, seleziona un collegamento di rete dall'elenco. Per maggiori informazioni, vedi Configura la lista consentita IP per i trasferimenti Salesforce.
    • Per Il mio dominio, inserisci Il mio dominio di Salesforce.
    • Per ID client, inserisci la chiave utente dell'applicazione collegata a Salesforce.
    • Per Client secret, inserisci il secret consumer dell'applicazione collegata a Salesforce.
    • Per Tipo di importazione, seleziona Completa o Incrementale.
    • Per Oggetti Salesforce da trasferire, fai clic su Sfoglia:
      • Seleziona gli oggetti da trasferire al set di dati di destinazione BigQuery. In questo campo puoi anche inserire manualmente gli oggetti da includere nel trasferimento di dati.
      • Se hai selezionato Aggiungi come modalità di scrittura incrementale, devi selezionare una colonna come colonna filigrana.
      • Se hai selezionato Upsert come modalità di scrittura incrementale, devi selezionare una colonna come colonna filigrana e poi selezionare una o più colonne come chiave primaria.

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

  6. Nella sezione Nome configurazione di trasferimento, per Nome visualizzato, inserisci un nome per il trasferimento di dati.

  7. Nella sezione Opzioni di pianificazione:

    • Nell'elenco Frequenza di ripetizione, seleziona un'opzione per specificare la frequenza con cui viene eseguito questo trasferimento di dati. Per specificare una frequenza di ripetizione personalizzata, seleziona Personalizzata. Se selezioni On demand, l'esecuzione avviene quando attivi manualmente il trasferimento.
    • Se applicabile, seleziona Inizia ora o Inizia all'ora impostata e fornisci una data di inizio e un'ora di esecuzione.

  8. (Facoltativo) Nella sezione Opzioni di notifica, segui questi passaggi:

    • Per attivare le notifiche via email, fai clic sul pulsante di attivazione/disattivazione Notifica email. Quando attivi questa opzione, l'amministratore del trasferimento riceve una notifica via email quando l'esecuzione di un trasferimento non riesce.
    • Per attivare le notifiche di esecuzione del trasferimento Pub/Sub per questo trasferimento, fai clic sul pulsante di attivazione/disattivazione Notifiche Pub/Sub. Puoi selezionare il nome del tuo argomento oppure fare clic su Crea un argomento per crearne uno.

  9. 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
    --params='PARAMETERS'

Dove:

  • PROJECT_ID (facoltativo): l'ID progetto Google Cloud . Se non viene fornito --project_id per specificare un progetto particolare, viene utilizzato il progetto predefinito.
  • DATA_SOURCE: l'origine dati salesforce.
  • NAME: il nome visualizzato per la configurazione del trasferimento dei dati. Il nome del trasferimento può essere qualsiasi valore che ti consenta di identificare il trasferimento se devi modificarlo in un secondo momento.
  • DATASET: il set di dati di destinazione per la configurazione del trasferimento.

  • PARAMETERS: i parametri per la configurazione del trasferimento creato in formato JSON. Ad esempio: --params='{"param":"param_value"}'. Di seguito sono riportati i parametri per un trasferimento di dati Salesforce:

    • connector.authentication.oauth.clientId: la chiave utente dell'applicazione collegata a Salesforce.
    • connector.authentication.oauth.clientSecret: client secret OAuth o consumer secret dell'applicazione connessa a Salesforce.
    • connector.authentication.oauth.myDomain: il Mio dominio Salesforce. Ad esempio, se l'URL del tuo dominio è example.my.salesforce.com, il valore è example.
    • ingestionType: specifica FULL o INCREMENTAL. I trasferimenti incrementali sono supportati nell'anteprima. Per maggiori informazioni, consulta Trasferimenti completi o incrementali.
    • writeMode: specifica WRITE_MODE_APPEND o WRITE_MODE_UPSERT.
    • watermarkColumns: specifica le colonne della tabella come colonne filigrana. Questo campo è obbligatorio per i trasferimenti incrementali.
    • primaryKeys: specifica le colonne della tabella come chiavi primarie. Questo campo è obbligatorio per i trasferimenti incrementali.
    • assets: il percorso degli oggetti Salesforce da trasferire a BigQuery.

Quando specifichi più asset durante un trasferimento incrementale, i valori dei campi watermarkColumns e primaryKeys corrispondono alla posizione dei valori nel campo assets. Nell'esempio seguente, Id corrisponde alla tabella Account, mentre master_label e type corrisponde alla tabella CaseHistory.

      "primaryKeys":[['Id'], ['master_label','type']],
      "assets":["Account","CaseHistory"],

Il comando seguente crea un trasferimento incrementale dei dati di Salesforce nel progetto predefinito e utilizza la modalità di scrittura APPEND.

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=salesforce
    --display_name='My Transfer'
    --params='{"assets": ["Account", "CaseHistory"]
        "connector.authentication.oauth.clientId": "1234567890",
        "connector.authentication.oauth.clientSecret":"ABC12345",
        "connector.authentication.oauth.myDomain":"MyDomainName",
        "connector.authentication.username":"user1@force.com",
        "connector.authentication.password":"abcdef1234",
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_UPSERT",
        "watermarkColumns":["SystemModstamp","CreatedDate"]
        "primaryKeys":[['Id'], ['master_label','type']]}'

API

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

Quando salvi la configurazione del trasferimento, il connettore Salesforce attiva automaticamente un'esecuzione del trasferimento in base all'opzione di pianificazione. A ogni esecuzione del trasferimento, il connettore Salesforce trasferisce tutti i dati disponibili da Salesforce a BigQuery.

Per eseguire manualmente un trasferimento di dati al di fuori della pianificazione regolare, puoi avviare un'esecuzione di backfill.

Mappatura dei tipi di dati

La seguente tabella mappa i tipi di dati di Salesforce con i corrispondenti tipi di dati di BigQuery:

Tipo di dati Salesforce Tipo di dati BigQuery
_bool BOOLEAN
_int INTEGER
_long INTEGER
_double FLOAT
currency FLOAT
percent FLOAT
geolocation (latitude) FLOAT
geolocation (longitude) FLOAT
date DATE
datetime TIMESTAMP
time TIME
picklist STRING
multipicklist STRING
combobox STRING
reference STRING
base64 STRING
textarea STRING
phone STRING
id STRING
url STRING
email STRING
encryptedstring STRING
datacategorygroupreference STRING
location STRING
address STRING
anyType STRING

Prezzi

Per informazioni sui prezzi dei trasferimenti da Salesforce, consulta la sezione Prezzi di Data Transfer Service.

Risolvere i problemi di configurazione del trasferimento

Se riscontri problemi durante la configurazione del trasferimento dei dati, consulta Problemi di trasferimento di Salesforce.

Passaggi successivi