Carica i dati di Salesforce in BigQuery

Per pianificare trasferimenti di dati ricorrenti da Salesforce Sales Cloud a BigQuery, crea una configurazione del trasferimento per specificare quali oggetti dati trasferire e con quale frequenza pianificare il trasferimento di dati. Puoi creare una configurazione del trasferimento utilizzando la console Google Cloud , lo strumento a riga di comando bq o l'API BigQuery Data Transfer Service. Una volta configurata la configurazione del trasferimento, BigQuery Data Transfer Service trasferisce i dati più recenti in una tabella BigQuery in base alla pianificazione specificata.

Per scoprire come funziona un trasferimento di dati di Salesforce, consulta Introduzione ai trasferimenti di dati di Salesforce.

Limitazioni

I trasferimenti di dati di Salesforce sono soggetti alle seguenti limitazioni:

  • Il connettore Salesforce supporta solo i trasferimenti da Salesforce Sales Cloud.
  • Il connettore Salesforce supporta solo i campi inclusi nell'API Salesforce Bulk V1 versione 64.0. 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 Salesforce Bulk.

  • Il connettore Salesforce utilizza l'API Salesforce Bulk V1 per connettersi all'endpoint Salesforce Sales Cloud per recuperare i dati.

    • Il connettore Salesforce supporta solo l'API Salesforce Bulk V1 per la connessione all'istanza Salesforce e supporta solo il trasferimento di entità supportate dall'API Salesforce Bulk. Per saperne di più sulle entità supportate, consulta 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 di Salesforce ai seguenti:

    • Non avere più di 10 asset per configurazione del 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 del trasferimento di dati alla volta. Nel caso in cui sia pianificata l'esecuzione di un secondo trasferimento di dati prima del completamento del primo, viene completato solo il primo trasferimento di dati, mentre vengono ignorati tutti gli altri trasferimenti di dati che si sovrappongono al primo.

    • Per evitare trasferimenti saltati all'interno di una singola configurazione del trasferimento, ti consigliamo di aumentare l'intervallo di tempo tra i trasferimenti di dati di grandi dimensioni configurando la Frequenza di ripetizione.

  • Se utilizzi collegamenti di rete con il trasferimento di dati, devi configurare un Network Address Translation (NAT) pubblico con un indirizzo IP statico. Per maggiori informazioni, vedi Configura la lista consentita IP per i trasferimenti Salesforce.

  • Se il collegamento di rete e l'istanza di macchina virtuale (VM) configurati si trovano in regioni diverse, potrebbe verificarsi uno spostamento di 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 di watermark.
  • L'importazione incrementale è supportata solo per gli asset con colonne di watermark valide.
  • I valori in una colonna di watermark devono essere in ordine crescente.
  • I trasferimenti incrementali non possono sincronizzare le operazioni di eliminazione nella tabella di origine.
  • Una singola configurazione del trasferimento può supportare solo l'acquisizione 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 del watermark o la chiave primaria dopo la prima esecuzione dell'importazione incrementale.
  • La tabella BigQuery di destinazione è raggruppata in cluster utilizzando la chiave primaria fornita ed è soggetta alle limitazioni delle tabelle in cluster.
  • Quando aggiorni una configurazione del trasferimento esistente alla modalità di importazione incrementale per la prima volta, il primo trasferimento di dati dopo l'aggiornamento trasferisce tutti i dati disponibili dall'origine dati. Tutti i trasferimenti di dati incrementali successivi trasferiranno solo le righe nuove e aggiornate dall'origine dati.

Per scoprire come funzionano i trasferimenti incrementali, consulta Trasferimenti completi o incrementali.

Prima di iniziare

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

Crea un'app collegata a Salesforce

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

  • Configura le informazioni di base nell'app connessa. I campi Nome app connessa ed Email di contatto sono obbligatori per un trasferimento Salesforce.
  • Attiva le impostazioni OAuth con le seguenti configurazioni:
    • Seleziona la casella di controllo Enable OAuth Settings (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 JSON Web Token (JWT) per gli utenti con nome non sia selezionata.
  • Nella sezione Selected OAuth Scopes (Ambiti OAuth selezionati), seleziona Manage user data via APIs (api) (Gestisci dati utente tramite API (api)).
  • Seleziona Enable Client Credentials Flow (Abilita flusso delle credenziali client), quindi fai clic su OK nella notifica visualizzata.

Dopo aver configurato l'app connessa con le configurazioni richieste, fai clic su Salva. Verrà 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 Edit (Modifica).
  5. Viene visualizzata la pagina Dettagli sull'app. Nella sezione Client Credentials Flow (Flusso di credenziali client), inserisci il tuo nome utente nel campo Run As (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 richieste su Salesforce

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

Nome parametro Descrizione
myDomain Il tuo My Domain 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 myDomain, clientID e clientSecret, seleziona una delle seguenti opzioni:

Salesforce Classic

Recupera 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 My Domain (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, myDomain viene visualizzato come prefisso in URL attuale del mio dominio. 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 ClientId e ClientSecret, segui questi passaggi:

  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 sul nome di un'app connessa.
  6. Nella pagina dei dettagli App collegate, 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 nuovamente la tua identità.
  8. Nella pagina Dettagli utente, la Chiave utente è il valore ClientId. Il secret del cliente è il valore ClientSecret.

Salesforce Lightning Experience

Recupera i dettagli di myDomain

Per trovare il tuo myDomain:

  1. Accedi alla piattaforma Salesforce.

  2. Fai clic su Configurazione.

    Apri la pagina Setup (Configurazione) nella piattaforma Salesforce.

  3. Nella barra di ricerca, cerca My Domain (Il mio dominio).

  4. Nei risultati di ricerca, fai clic su Company Settings (Impostazioni azienda) > My Domain (Il mio dominio).

Nella sezione Dettagli del mio dominio, myDomain viene visualizzato come prefisso in URL attuale del mio dominio. 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

  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 connessa, quindi 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 nuovamente la tua identità.
  8. Nella pagina Dettagli utente, la Chiave utente è il valore ClientId. Il secret del cliente è il valore ClientSecret.

Configura la lista consentita IP per i trasferimenti Salesforce

Devi configurare l'ambiente Google Cloud e l'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. Questo passaggio è obbligatorio se utilizzi i collegamenti di rete con i trasferimenti di dati.

Per farlo, devi prima configurare la rete Google Cloud per utilizzare un indirizzo IP statico:

  1. Configura un Network Address Translation (NAT) pubblico 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 dell'indirizzo IP, utilizza l'indirizzo IP statico del tuo NAT pubblicoGoogle Cloud sia per l'indirizzo IP iniziale sia per quello finale dell'intervallo IP.

Dopo aver configurato gli intervalli IP, puoi specificare l'IP statico quando configuri il trasferimento selezionando il collegamento di rete nel campo Collegamento 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 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 di 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 di 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 saperne di più, consulta Concedi l'accesso a bigquery.admin.

Configura un trasferimento di dati da Salesforce

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

Console

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

    Vai a Trasferimenti di 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. Prima di poter utilizzare un collegamento di rete con questo trasferimento di dati, devi configurare il Public NAT e impostare la lista consentita di IP.
    • 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.
      • Se selezioni Incrementale per Modalità di scrittura, seleziona Aggiungi o Esegui upsert. Per saperne di più sulle diverse modalità di scrittura, consulta Trasferimenti completi o incrementali.
    • 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 watermark.
      • Se hai selezionato Esegui upsert come modalità di scrittura incrementale, devi selezionare una colonna come colonna watermark, e poi 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 della 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: il set di dati di destinazione per la configurazione del trasferimento.

  • PARAMETERS: 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 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 dominio Salesforce. Ad esempio, se l'URL del tuo dominio è example.my.salesforce.com, il valore è example.
    • ingestionType: specifica full o incremental. Per saperne di più, consulta Trasferimenti completi o incrementali.
    • writeMode: specifica WRITE_MODE_APPEND o WRITE_MODE_UPSERT.
    • watermarkColumns: specifica le colonne della tabella come colonne di watermark. 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 corrispondono alla tabella CaseHistory.

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

Il comando seguente crea un trasferimento di dati Salesforce incrementale 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.

Risolvi i problemi di configurazione del trasferimento

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

Passaggi successivi