Questa pagina è stata tradotta dall'API Cloud Translation.

Integrazione con Salesforce (SFDC)

Questa pagina descrive i passaggi di integrazione per il carico di lavoro operativo di Salesforce (SFDC) nella Data Foundation di Cortex Framework. Cortex Framework integra i dati di Salesforce con le pipeline Dataflow in BigQuery, mentre Cloud Composer pianifica e monitora queste pipeline Dataflow per ottenere insight dai tuoi dati.

File di configurazione

Il file config.json nel repository Cortex Framework Data Foundation configura le impostazioni necessarie per trasferire i dati da qualsiasi origine dati, inclusa Salesforce. Questo file contiene i seguenti parametri per i carichi di lavoro operativi di Salesforce:

    "SFDC": {
        "deployCDC": true,
        "createMappingViews": true,
        "createPlaceholders": true,
        "datasets": {
            "cdc": "",
            "raw": "",
            "reporting": "REPORTING_SFDC"
        }
    }

La seguente tabella descrive il valore di ciascun parametro operativo SFDC:

Parametro	Significato	Valore predefinito	Descrizione
`SFDC.deployCDC`	Esegui il deployment di CDC	`true`	Genera script di elaborazione CDC da eseguire come DAG in Cloud Composer. Consulta la documentazione per le diverse opzioni di importazione per Salesforce Sales Cloud.
`SFDC.createMappingViews`	Creare viste di mappatura	`true`	I DAG forniti per recuperare nuovi record dalle API Salesforce aggiornano i record nella pagina di destinazione. Se questo valore è impostato su true, vengono generate visualizzazioni nel set di dati elaborato CDC per esporre tabelle con la "versione più recente dei dati di fatto" del set di dati non elaborato. Se false e `SFDC.deployCDC` è `true`, i DAG vengono generati con l'elaborazione Change Data Capture (CDC) in base a SystemModstamp. Consulta i dettagli sull'elaborazione CDC per Salesforce.
`SFDC.createPlaceholders`	Creare segnaposto	`true`	Crea tabelle segnaposto vuote nel caso in cui non vengano generate dal processo di importazione per consentire l'esecuzione del deployment dei report downstream senza errori.
`SFDC.datasets.raw`	Set di dati di destinazione non elaborati	-	Utilizzato dal processo CDC, è qui che lo strumento di replica inserisce i dati da Salesforce. Se utilizzi dati di test, crea un set di dati vuoto.
`SFDC.datasets.cdc`	Set di dati elaborato CDC	-	Dataset che funge da origine per le visualizzazioni dei report e da destinazione per i DAG di record elaborati. Se utilizzi dati di test, crea un set di dati vuoto.
`SFDC.datasets.reporting`	Set di dati dei report SFDC	`"REPORTING_SFDC"`	Nome del set di dati accessibile agli utenti finali per la generazione di report, in cui vengono implementate le viste e le tabelle rivolte agli utenti.
`SFDC.currencies`	Filtro delle valute	`[ "USD" ]`	Se non utilizzi dati di test, inserisci una singola valuta (ad esempio `[ "USD" ]`) o più valute (ad esempio `[ "USD", "CAD" ]`) in base alle esigenze della tua attività. Questi valori vengono utilizzati per sostituire i segnaposto in SQL nei modelli di analisi ove disponibili.

Modello dati

Questa sezione descrive il modello di dati Salesforce (SFDC) utilizzando il diagramma delle relazioni tra entità (ERD).

Figura 2. Salesforce (SFDC): diagramma delle relazioni tra entità.

Visualizzazioni di base

Si tratta degli oggetti blu nel diagramma ERD e sono viste delle tabelle CDC senza trasformazioni, ad eccezione di alcuni alias dei nomi delle colonne. Vedi gli script in src/SFDC/src/reporting/ddls.

Viste report

Si tratta degli oggetti verdi nel diagramma ERD e contengono gli attributi dimensionali pertinenti utilizzati dalle tabelle dei report. Vedi gli script in src/SFDC/src/reporting/ddls.

Requisiti dei dati Salesforce

Questa sezione descrive in dettaglio come devono essere strutturati i dati di Salesforce per essere utilizzati con Cortex Framework.

Struttura della tabella:
- Denominazione:i nomi delle tabelle utilizzano snake_case (parole minuscole separate da trattini bassi) e sono al plurale. Ad esempio: some_objects.
- Tipi di dati:le colonne mantengono gli stessi tipi di dati rappresentati in Salesforce.
- Leggibilità:alcuni nomi dei campi potrebbero essere leggermente modificati per una maggiore chiarezza nel livello di reporting.
Tabelle vuote e deployment:le tabelle richieste mancanti nel set di dati non elaborato vengono create automaticamente come tabelle vuote durante il processo di deployment. In questo modo, l'esecuzione del passaggio di deployment del CDC avviene senza problemi.
Requisiti CDC:i campi Id e SystemModstamp sono fondamentali per consentire agli script CDC di monitorare le modifiche ai dati. Possono avere questi nomi esatti o nomi diversi. Gli script di elaborazione non elaborati forniti recuperano automaticamente questi campi dalle API e aggiornano la tabella di replica di destinazione.
- Id: funge da identificatore univoco per ogni record.
- SystemModstamp: questo campo memorizza un timestamp che indica l'ultima volta che un record è stato modificato.
Script di elaborazione raw:gli script di elaborazione raw forniti non richiedono un'elaborazione aggiuntiva (CDC). Questo comportamento è impostato per impostazione predefinita durante il deployment.

Tabelle di origine per la conversione di valuta

Salesforce ti consente di gestire le valute in due modi:

Di base:questa è l'impostazione predefinita, in cui tutti i dati utilizzano una singola valuta.
Avanzata: esegue la conversione tra più valute in base ai tassi di cambio (richiede l'attivazione della gestione avanzata delle valute).

Se utilizzi la gestione avanzata delle valute, Salesforce utilizza due tabelle speciali:

CurrencyTypes: questa tabella memorizza informazioni sulle diverse valute che utilizzi (ad esempio USD, EUR e così via).
DatedConversionRates: questa tabella contiene i tassi di cambio tra le valute nel tempo.

Cortex Framework prevede la presenza di queste tabelle se utilizzi la gestione avanzata delle valute. Se non utilizzi la gestione avanzata delle valute, puoi rimuovere le voci relative a queste tabelle da un file di configurazione (src/SFDC/config/ingestion_settings.yaml). Questo passaggio impedisce tentativi non necessari di estrazione dei dati da tabelle inesistenti.

Caricamento dei dati SFDC in BigQuery

Cortex Framework fornisce una soluzione di replica basata su script Python pianificati in Apache Airflow e nell'API Salesforce Bulk 2.0. Questi script Python possono essere adattati e pianificati nello strumento che preferisci. Per ulteriori informazioni, consulta la sezione Modulo di estrazione SFDC.

Cortex Framework offre anche tre metodi diversi per integrare i dati, a seconda della provenienza e della modalità di gestione:

Chiamate API:questa opzione è per i dati a cui è possibile accedere direttamente tramite un'API. Cortex Framework può chiamare l'API, recuperare i dati e archiviarli in un set di dati "Raw" all'interno di BigQuery. Se nel set di dati sono presenti record esistenti, Cortex Framework può aggiornarli con i nuovi dati.
Viste di mappatura della struttura:questo metodo è utile se hai già caricato i dati in BigQuery tramite un altro strumento, ma la struttura dei dati non corrisponde a quella richiesta da Cortex Framework. Cortex Framework utilizza le "visualizzazioni" (come le tabelle virtuali) per tradurre la struttura dei dati esistente nel formato previsto dalle funzionalità di generazione di report di Cortex Framework.
Script di elaborazione CDC (Change Data Capture):questa opzione è progettata specificamente per i dati in continua evoluzione. Gli script CDC monitorano queste modifiche e aggiornano i dati in BigQuery di conseguenza. Questi script si basano su due campi speciali nei tuoi dati:
- Id: identificatore univoco per ogni record.
- SystemModstamp: un timestamp che indica quando è stato modificato un record.
Se i tuoi dati non hanno questi nomi esatti, gli script possono essere modificati per riconoscerli con nomi diversi. Durante questo processo, puoi anche aggiungere campi personalizzati allo schema dei dati. Ad esempio, la tabella di origine con i dati dell'oggetto Account deve avere i campi Id e SystemModstamp originali. Se questi campi hanno nomi diversi, il file src/SFDC/src/table_schema/accounts.csv deve essere aggiornato con il nome del campo Id mappato a AccountId e il campo timestamp di modifica del sistema mappato a SystemModstamp. Per saperne di più, consulta la documentazione di SystemModStamp.

Se hai già caricato i dati tramite un altro strumento (e vengono aggiornati costantemente), Cortex può comunque utilizzarli. Gli script CDC sono forniti con file di mapping che possono tradurre la struttura dei dati esistente nel formato richiesto da Cortex Framework. Durante questo processo, puoi anche aggiungere campi personalizzati ai tuoi dati.

Configura l'integrazione dell'API e CDC

Per importare i dati di Salesforce in BigQuery, puoi utilizzare i seguenti metodi:

Script Cortex per chiamate API: fornisce script di replica per Salesforce o uno strumento di replica dei dati a tua scelta.La chiave è che i dati che importi devono avere lo stesso aspetto di quelli provenienti dalle API Salesforce.
Strumento di replica e aggiunta sempre : se utilizzi uno strumento per la replica, questo metodo è adatto a uno strumento che può aggiungere nuovi record di dati (_appendalways_pattern) o aggiornare i record esistenti.
Strumento di replica e aggiunta di nuovi record: se lo strumento non aggiorna i record e replica le modifiche come nuovi record in una tabella di destinazione (non elaborata), Cortex Data Foundation offre la possibilità di creare script di elaborazione CDC. Per saperne di più, consulta la procedura CDC.

Carico di lavoro Salesforce: opzioni di integrazione dei dati

Figura 1. Carico di lavoro Salesforce: opzioni di integrazione dei dati.

Per assicurarti che i dati corrispondano a quelli previsti da Cortex Framework, puoi modificare la configurazione del mapping per mappare lo strumento di replica o gli schemi esistenti. In questo modo vengono generate viste di mapping compatibili con la struttura prevista da Cortex Framework Data Foundation.

Utilizza il file ingestion_settings.yaml per configurare la generazione di script per chiamare le API Salesforce e replicare i dati nel set di dati non elaborati (sezione salesforce_to_raw_tables) e la generazione di script per elaborare le modifiche in arrivo nel set di dati non elaborati e nel set di dati elaborati CDC (sezione raw_to_cdc_tables).

Per impostazione predefinita, gli script forniti per la lettura dalle API aggiornano le modifiche nel set di dati non elaborati, pertanto non sono necessari script di elaborazione CDC e vengono create visualizzazioni di mapping per allineare lo schema di origine allo schema previsto.

La generazione degli script di elaborazione CDC non viene eseguita se SFDC.createMappingViews=true in config.json (comportamento predefinito). Se sono necessari script CDC, imposta SFDC.createMappingViews=false. Questo secondo passaggio consente anche la mappatura tra gli schemi di origine e gli schemi richiesti da Cortex Framework Data Foundation.

Il seguente esempio di file di configurazione setting.yaml illustra la generazione di viste di mappatura quando uno strumento di replica aggiorna i dati direttamente nel set di dati replicato, come illustrato in option 3 (ovvero non è richiesto alcun CDC, solo la rimappatura di tabelle e nomi dei campi). Poiché non è richiesto alcun CDC, questa opzione viene eseguita finché il parametro SFDC.createMappingViews nel file config.json rimane true.

  salesforce_to_raw_tables:
  - base_table: accounts
    raw_table: Accounts
    api_name: Account
      load_frequency: "@daily"
  - base_table: cases
    raw_table: cases2
    api_name: Case
    load_frequency: "@daily"

In questo esempio, la rimozione della configurazione per una tabella di base o di tutte dalle sezioni salta la generazione di DAG di quella tabella di base o dell'intera sezione, come illustrato per salesforce_to_raw_tables. Per questo scenario, l'impostazione del parametro deployCDC : False ha lo stesso effetto, in quanto è necessario generare script di elaborazione non CDC.

Mappatura dei dati

Devi mappare i campi di dati in entrata al formato previsto da Cortex Data Foundation. Ad esempio, un campo denominato unicornId nel sistema di dati di origine deve essere rinominato e riconosciuto come AccountId (con un tipo di dati stringa) in Cortex Data Foundation:

Campo origine: unicornId (nome utilizzato nel sistema di origine)
Campo Cortex: AccountId (nome previsto da Cortex)
Tipo di dati: String (tipo di dati previsto da Cortex)

Mappare i campi polimorfici

Cortex Framework Data Foundation supporta la mappatura dei campi polimorfici, ovvero campi il cui nome può variare, ma la cui struttura rimane coerente. I nomi dei tipi di campi polimorfici (ad esempio Who.Type) possono essere replicati aggiungendo un elemento [Field Name]_Type nei rispettivi file CSV di mappatura: src/SFDC/src/table_schema/tasks.csv. Ad esempio, se devi replicare il campo Who.Type dell'oggetto Task, aggiungi la riga Who_Type,Who_Type,STRING. Definisce un nuovo campo denominato Who.Type che esegue la mappatura a se stesso (mantiene lo stesso nome) e ha un tipo di dati stringa.

Modificare i modelli DAG

Potresti dover modificare i modelli DAG per CDC o per l'elaborazione dei dati non elaborati in base alle esigenze della tua istanza di Airflow o Cloud Composer. Per saperne di più, vedi Raccolta delle impostazioni di Cloud Composer.

Se non hai bisogno di CDC o della generazione di dati non elaborati dalle chiamate API, imposta deployCDC=false. In alternativa, puoi rimuovere i contenuti delle sezioni in ingestion_settings.yaml. Se è noto che le strutture dei dati sono coerenti con quelle previste da Cortex Framework Data Foundation, puoi saltare la generazione di viste di mappatura impostando SFDC.createMappingViews=false.

Configurazione del modulo di estrazione

Questa sezione descrive i passaggi per utilizzare il modulo di estrazione da Salesforce a BigQuery fornito da Data Foundation. I requisiti e il flusso potrebbero variare a seconda del sistema e della configurazione esistente. In alternativa, puoi utilizzare altri strumenti disponibili.

Configurare le credenziali e l'app collegata

Accedi come amministratore alla tua istanza Salesforce per completare le seguenti operazioni:

Crea o identifica un profilo in Salesforce che soddisfi i seguenti requisiti:
1. Permission for Apex REST Services and API Enabled viene concesso in Autorizzazioni di sistema.
2. L'autorizzazione View All viene concessa per tutti gli oggetti che vuoi replicare. Ad esempio, Account e Richieste. Verifica la presenza di limitazioni o problemi con l'amministratore della sicurezza.
3. Nessuna autorizzazione concessa per l'accesso all'interfaccia utente, come Salesforce Anywhere in Lightning Experience, Salesforce Anywhere su dispositivi mobili, Utente Lightning Experience e Utente di accesso Lightning. Verifica la presenza di limitazioni o problemi con il tuo amministratore della sicurezza.
Crea o utilizza un utente esistente in Salesforce. Devi conoscere il nome utente, la password e il token di sicurezza dell'utente. Considera quanto segue:
- Idealmente, dovrebbe essere un utente dedicato all'esecuzione di questa replica.
- L'utente deve essere assegnato al profilo che hai creato o identificato nel passaggio 1.
- Qui puoi visualizzare il nome utente e reimpostare la password.
- Puoi reimpostare il token di sicurezza se non lo hai e non viene utilizzato da un altro processo.
Crea un'app connessa. È l'unico canale di comunicazione per stabilire la connessione a Salesforce dal mondo esterno con l'aiuto del profilo, dell'API Salesforce, delle credenziali utente standard e del relativo token di sicurezza.
1. Segui le istruzioni per abilitare le impostazioni OAuth per l'integrazione API.
2. Assicurati che Require Secret for Web Server Flow e Require Secretfor Refresh Token Flow siano abilitati nella sezione API (Enabled OAuth Settings) (API (Abilita impostazioni OAuth)).
3. Consulta la documentazione su come ottenere la tua consumer key (che verrà utilizzata in un secondo momento come ID client). Contatta l'amministratore della sicurezza per problemi o limitazioni.
Assegna l'app connessa al profilo creato.
1. Seleziona Configurazione in alto a destra nella schermata Home di Salesforce.
2. Nella casella Ricerca rapida, inserisci profile, quindi seleziona Profilo. Cerca il profilo creato al passaggio 1.
3. Apri il profilo.
4. Fai clic sul link App collegate assegnate.
5. Fai clic su Modifica.
6. Aggiungi l'app connessa appena creata.
7. Fai clic sul pulsante Salva.

Configura Secret Manager

Configura Secret Manager per archiviare i dettagli della connessione. Il modulo Salesforce-to-BigQuery si basa su Secret Manager per archiviare in modo sicuro le credenziali necessarie per connettersi a Salesforce e BigQuery. Questo approccio evita di esporre informazioni sensibili come le password direttamente nel codice o nei file di configurazione, migliorando la sicurezza.

Crea un secret con le seguenti specifiche. Per istruzioni più dettagliate, vedi Creare un secret.

Nome segreto: airflow-connections-salesforce-conn
Valore secret:
```
http://USERNAME:PASSWORD@https%3A%2F%2FINSTANCE_NAME.lightning.force.com?client_id=CLIENT_ID&security_token=SECRET_TOKEN`
```
Sostituisci quanto segue:
- USERNAME con il tuo nome utente.
- PASSWORD con la tua password.
- INSTANCE_NAME con il nome dell'istanza.
- CLIENT_ID con il tuo ID client.
- SECRET_TOKEN con il token del secret.

Per saperne di più, consulta Come trovare il nome dell'istanza.

Librerie Cloud Composer per la replica

Per eseguire gli script Python nei DAG forniti da Cortex Framework Data Foundation, devi installare alcune dipendenze. Per Airflow versione 1.10, segui la documentazione Installare le dipendenze Python per Cloud Composer 1 per installare i seguenti pacchetti, in ordine:

tableauserverclient==0.17
apache-airflow-backport-providers-salesforce==2021.3.3

Per Airflow versione 2.x, consulta la documentazione Installare le dipendenze Python per Cloud Composer 2 per installare apache-airflow-providers-salesforce~=5.2.0.

Utilizza il seguente comando per installare ogni pacchetto richiesto:

  gcloud composer environments update ENVIRONMENT_NAME \
  --location LOCATION \
   --update-pypi-package PACKAGE_NAME EXTRAS_AND_VERSION

Sostituisci quanto segue:

ENVIRONMENT_NAME con il nome dell'ambiente assegnato.
LOCATION con la posizione.
PACKAGE_NAME con il nome del pacchetto scelto.
EXTRAS_AND_VERSION con le specifiche degli extra e della versione.

Il seguente comando è un esempio di installazione di un pacchetto obbligatorio:

gcloud composer environments update my-composer-instance \
  --location us-central1 \
  --update-pypi-package apache-airflow-backport-providers-salesforce>=2021.3.3

Abilita Secret Manager come backend

Abilita Google Secret Manager come backend di sicurezza. Questo passaggio ti chiede di attivare Secret Manager come posizione di archiviazione principale per informazioni sensibili come password e chiavi API utilizzate dal tuo ambiente Cloud Composer. In questo modo la sicurezza viene migliorata centralizzando e gestendo le credenziali in un servizio dedicato. Per ulteriori informazioni, consulta Secret Manager.

Consenti al account di servizio Composer di accedere ai secret

Questo passaggio garantisce che il account di servizio associato a Cloud Composer disponga delle autorizzazioni necessarie per accedere ai secret archiviati in Secret Manager. Per impostazione predefinita, Cloud Composer utilizza il account di servizio Compute Engine. L'autorizzazione richiesta è Secret Manager Secret Accessor. Questa autorizzazione consente al account di servizio di recuperare e utilizzare i secret archiviati in Secret Manager.Per una guida completa alla configurazione dei controlli dell'accesso in Secret Manager, consulta la documentazione sul controllo dell'accesso.

Connessione BigQuery in Airflow

Assicurati di creare la connessione sfdc_cdc_bq in base a Raccolta delle impostazioni di Cloud Composer. Questa connessione viene probabilmente utilizzata dal modulo Salesforce-to-BigQuery per stabilire la comunicazione con BigQuery.

Passaggi successivi

Per saperne di più su altre origini dati e altri carichi di lavoro, vedi Origini dati e carichi di lavoro.
Per ulteriori informazioni sui passaggi per il deployment negli ambienti di produzione, consulta Prerequisiti per il deployment di Cortex Framework Data Foundation.