Copiare dati da e in Salesforce V1 usando Azure Data Factory o Azure Synapse Analytics

Articolo
10/15/2024

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Suggerimento

Provare Data Factory in Microsoft Fabric, una soluzione di analisi all-in-one per le aziende. Microsoft Fabric copre tutto, dallo spostamento dati al data science, all'analisi in tempo reale, alla business intelligence e alla creazione di report. Vedere le informazioni su come iniziare una nuova prova gratuita!

Questo articolo descrive come usare l'attività di copia in Azure Data Factory e nelle pipeline di Azure Synapse per copiare dati da e verso Salesforce. Si basa sull'articolo di panoramica dell'attività di copia che presenta informazioni generali sull'attività di copia.

Importante

Il connettore Salesforce V2 offre un supporto di Salesforce nativo migliorato. Se si usa il connettore Salesforce V1 nella soluzione, è consigliabile aggiornare il connettore Salesforce al più presto. Per informazioni dettagliate sulla differenza tra V2 e V1, vedere questa sezione .

Funzionalità supportate

Questo connettore Salesforce è supportato per le funzionalità seguenti:

Funzionalità supportate	IR
Attività di copia (origine/sink)	(1) (2)
Attività Lookup	(1) (2)

① Azure Integration Runtime ② Runtime di integrazione self-hosted

Per un elenco degli archivi dati supportati come origini o sink, vedere la tabella Archivi dati supportati.

In particolare, il connettore Salesforce supporta:

Le edizioni Developer, Professional, Enterprise o Unlimited di Salesforce.
La copia di dati da e nell'ambiente di produzione, nella sandbox e nel dominio personalizzato di Salesforce.

Nota

Questa funzione supporta la copia di qualsiasi schema dagli ambienti Salesforce indicati in precedenza, incluso NPSP (Nonprofit Success Pack).

Il connettore Salesforce si basa sull'API REST\Bulk di Salesforce. Quando si copiano dati da Salesforce, il connettore sceglie automaticamente tra le API REST e Bulk in base alle dimensioni dei dati. Quando il set di risultati è di grandi dimensioni, viene usata l'API Bulk per ottenere prestazioni migliori. È possibile impostare in modo esplicito la versione dell'API usata per leggere/scrivere dati tramite la proprietà apiVersion nel servizio collegato. Quando si copiano dati in Salesforce, il connettore usa l'API BULK v1.

Nota

Il connettore non imposta più la versione predefinita per l'API Salesforce. Per garantire la compatibilità con le versioni precedenti, se è stata impostata in precedenza, la versione API predefinita continua a funzionare. Il valore predefinito è 45.0 per source e 40.0 per sink.

Prerequisiti

In Salesforce deve essere abilitata l'autorizzazione API.

Limiti delle richieste Salesforce

Salesforce presenta limiti per le richieste API totali e per le richieste API simultanee. Tenere presente quanto segue:

Se il numero di richieste simultanee supera il limite, si verifica una limitazione e vengono visualizzati errori casuali.
Se il numero totale di richieste supera il limite, l'account di Salesforce viene bloccato per 24 ore.

In entrambi gli scenari è anche possibile che venga visualizzato il messaggio di errore "REQUEST_LIMIT_EXCEEDED" ("LIMITE_RICHIESTE_SUPERATO"). Per altre informazioni, vedere la sezione "API Request Limits" (Limiti delle richieste API) in Salesforce developer limits (Limiti per sviluppatori di Salesforce).

Operazioni preliminari

Per eseguire l'attività di copia con una pipeline, è possibile usare uno degli strumenti o SDK seguenti:

Creare un servizio collegato a Salesforce tramite l'interfaccia utente

Usare la procedura seguente per creare un servizio collegato a Salesforce nell'interfaccia utente del portale di Azure.

Passare alla scheda Gestisci nell'area di lavoro di Azure Data Factory o Synapse e selezionare Servizi collegati, quindi fare clic su Nuovo:
- Azure Data Factory
- Azure Synapse
Cercare Salesforce e selezionare il connettore Salesforce.
Configurare i dettagli del servizio, testare la connessione e creare il nuovo servizio collegato.

Dettagli di configurazione del connettore

Le sezioni seguenti riportano informazioni dettagliate sulle proprietà usate per definire entità specifiche per il connettore Salesforce.

Proprietà del servizio collegato

Per il servizio collegato di Salesforce sono supportate le proprietà seguenti.

Proprietà	Descrizione	Richiesto
type	La proprietà type deve essere impostata su Salesforce.	Sì
environmentUrl	Specificare l'URL dell'istanza di Salesforce. - Il valore predefinito è `"https://login.salesforce.com"`. - Per copiare dati dalla sandbox, specificare `"https://test.salesforce.com"`. - Per copiare dati dal dominio personalizzato, specificare ad esempio `"https://[domain].my.salesforce.com"`.	No
username	Specificare un nome utente per l'account utente.	Sì
password	Specificare la password per l'account utente. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro oppure fare riferimento a un segreto archiviato in Azure Key Vault.	Sì
securityToken	Specificare un token di sicurezza per l'account utente. Per informazioni generali sui token di sicurezza, vedere Security and the API(Sicurezza e API). Il token di sicurezza può essere ignorato solo se si aggiunge l'indirizzo IP di Integration Runtime all'elenco di indirizzi IP attendibili in Salesforce. Quando si usa Azure Integration Runtime, vedere Indirizzi IP di Azure Integration Runtime. Per istruzioni su come ottenere e reimpostare un token di sicurezza, vedere Ottenere un token di sicurezza. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro oppure fare riferimento a un segreto archiviato in Azure Key Vault.	No
apiVersion	Specificare la versione depp'API REST Salesforce/API Bulk da usare, ad esempio `52.0`.	No
connectVia	Runtime di integrazione da usare per la connessione all'archivio dati. Se non specificato, viene usato il runtime di integrazione di Azure predefinito.	No

Esempio: archiviare le credenziali

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            },
            "securityToken": {
                "type": "SecureString",
                "value": "<security token>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Esempio: Archiviare le credenziali in Key Vault

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Esempio: archiviare le credenziali in Key Vault, nonché environmentUrl e username

Si noti che, in questo modo, non sarà più possibile usare l'interfaccia utente per modificare le impostazioni. La casella di controllo Specificare il contenuto dinamico nel formato JSON verrà selezionata e sarà necessario modificare completamente questa configurazione a mano. Il vantaggio è che è possibile derivare TUTTE le impostazioni di configurazione da Key Vault invece di parametrizzare qualsiasi elemento qui.

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "environmentUrl": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of environment URL in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "username": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of username in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Proprietà del set di dati

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere l'articolo Set di dati. Questa sezione presenta un elenco delle proprietà supportate dal set di dati Salesforce.

Per copiare dati da e in Salesforce, impostare la proprietà type del set di dati su SalesforceObject. Sono supportate le proprietà seguenti.

Proprietà	Descrizione	Richiesto
type	La proprietà type deve essere impostata su SalesforceObject.	Sì
objectApiName	Nome dell'oggetto di Salesforce da cui recuperare i dati.	No per l'origine, Sì per il sink

Importante

La parte "__c" delnome dell'API è necessaria per qualsiasi oggetto personalizzato.

Screenshot che mostra il nome dell'API di connessione Salesforce.

Esempio:

{
    "name": "SalesforceDataset",
    "properties": {
        "type": "SalesforceObject",
        "typeProperties": {
            "objectApiName": "MyTable__c"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Salesforce linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Nota

Per compatibilità con le versioni precedenti, quando si copiano dati da Salesforce, l'uso del set di dati di tipo "RelationalTable" precedente continua a funzionare, anche se viene consigliato di passare all'uso del nuovo tipo "SalesforceObject".

Proprietà	Descrizione	Richiesto
type	La proprietà type del set di dati deve essere impostata su RelationalTable.	Sì
tableName	Nome della tabella in Salesforce.	No (se nell'origine dell'attività è specificato "query")

Proprietà dell'attività di copia

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline. Questa sezione presenta un elenco delle proprietà supportate dall'origine e dal sink Salesforce.

Salesforce come tipo di origine

Per copiare dati da Salesforce, impostare il tipo di origine nell'attività di copia su SalesforceSource. Nella sezione source dell'attività di copia sono supportate le proprietà seguenti.

Proprietà	Descrizione	Richiesto
type	La proprietà type dell'origine dell'attività di copia deve essere impostata su SalesforceSource.	Sì
query	Usare la query personalizzata per leggere i dati. È possibile usare una query SQL-92 o una query Salesforce Object Query Language (SOQL). Vedere altri suggerimenti nella sezione Suggerimenti di query. Se la proprietà query non viene specificata, tutti i dati dell'oggetto Salesforce specificato in "objectApiName" nel set di dati verranno recuperati.	No (se "objectApiName" è specificato nel set di dati)
readBehavior	Indica se eseguire query sui record esistenti o su tutti i record inclusi quelli eliminati. Se non specificato, il comportamento predefinito è quello indicato per primo. Valori consentiti: query (predefinito), queryAll.	No

Importante

La parte "__c" delnome dell'API è necessaria per qualsiasi oggetto personalizzato.

Screenshot che mostra l'elenco di nomi dell'API di connessione Salesforce.

Esempio:

"activities":[
    {
        "name": "CopyFromSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Salesforce input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SalesforceSource",
                "query": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Nota

Per compatibilità con le versioni precedenti, quando si copiano dati da Salesforce, se si usa il tipo "RelationalSource" precedente, l'origine continua a funzionare anche se viene consigliato di passare all'uso del nuovo tipo "SalesforceSource".

Nota

L'origine Salesforce non supporta le impostazioni proxy nel runtime di integrazione self-hosted, ma il sink le supporta.

Salesforce come tipo di sink

Per copiare dati in Salesforce, impostare il tipo di sink nell'attività di copia su SalesforceSink. Nella sezione sink dell'attività di copia sono supportate le proprietà seguenti.

Proprietà	Descrizione	Richiesto
type	La proprietà type del sink dell'attività di copia deve essere impostata su SalesforceSink.	Sì
writeBehavior	Comportamento dell'azione di scrittura per l'operazione. I valori consentiti sono: Insert e Upsert.	No (il valore predefinito è Insert)
externalIdFieldName	Nome del campo ID esterno per l'operazione upsert. Il campo specificato deve essere definito come "External ID Field" nell'oggetto di Salesforce. Non può includere valori NULL nei dati di input corrispondenti.	Sì per "Upsert"
writeBatchSize	Conteggio delle righe di dati scritti da Salesforce in ogni batch.	No (il valore predefinito è 5.000)
ignoreNullValues	Indica se ignorare i valori NULL dai dati di input durante un'operazione di scrittura. I valori consentiti sono true e false. - True: i dati nell'oggetto di destinazione rimangono invariati quando si esegue un'operazione di upsert o aggiornamento. Inserire un valore predefinito definito quando si esegue un'operazione di inserimento. - False: i dati nell'oggetto di destinazione vengono aggiornati a NULL quando si esegue un'operazione di upsert o aggiornamento. Inserire un valore NULL quando si esegue un'operazione di inserimento.	No (il valore predefinito è false)
maxConcurrentConnections	Limite massimo di connessioni simultanee stabilite all'archivio dati durante l'esecuzione dell'attività. Specificare un valore solo quando si desidera limitare le connessioni simultanee.	No

Esempio: Sink Salesforce in un'attività di copia

"activities":[
    {
        "name": "CopyToSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Salesforce output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "SalesforceSink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

Suggerimenti di query

Recuperare dati da un report di Salesforce

È possibile recuperare dati dai report di Salesforce specificando una query come {call "<report name>"}. Un esempio è "query": "{call \"TestReport\"}".

Recuperare i record eliminati dal Cestino di Salesforce

Per recuperare i record eliminati temporaneamente dal Cestino di Salesforce, è possibile specificare readBehavior come queryAll.

Differenza tra la sintassi di query SOQL e SQL

Quando si copiano dati da Salesforce, è possibile usare una query SOQL o SQL. Si noti che queste due query hanno una sintassi e un supporto di funzionalità diversi. Non mischiarli. È consigliabile usare la query SOQL, supportata in modo nativo da Salesforce. Nella tabella seguente sono elencate le differenze principali:

Sintassi	Modalità SOQL	Modalità SQL
Selezione di colonne	È necessario enumerare i campi da copiare nella query, ad esempio `SELECT field1, filed2 FROM objectname`	`SELECT *` è supportata oltre alla selezione della colonna.
Virgolette	I nomi di campo/oggetto non possono essere racchiusi tra virgolette.	I nomi di campo/oggetto non possono essere racchiusi tra virgolette, ad es. `SELECT "id" FROM "Account"`
Formato datetime	Fare riferimento a informazioni dettagliate qui ed esempi nella sezione successiva.	Fare riferimento a informazioni dettagliate qui ed esempi nella sezione successiva.
Valori booleani	Rappresentati come `False` e `True`, ad esempio `SELECT … WHERE IsDeleted=True`.	Rappresentati come 0 o 1, ad esempio `SELECT … WHERE IsDeleted=1`.
Ridenominazione delle colonne	Non supportato.	Supportata, ad es. `SELECT a AS b FROM …`.
Relationship	Supportata, ad es. `Account_vod__r.nvs_Country__c`.	Non supportato.

Recuperare i dati usando una clausola where nella colonna DateTime

Quando si specifica la query SOQL o SQL, prestare attenzione alla differenza di formato di DateTime. Ad esempio:

Esempio SOQL: SELECT Id, Name, BillingCity FROM Account WHERE LastModifiedDate >= @{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-ddTHH:mm:ssZ')} AND LastModifiedDate < @{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-ddTHH:mm:ssZ')}
Esempio SQL: SELECT * FROM Account WHERE LastModifiedDate >= {ts'@{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-dd HH:mm:ss')}'} AND LastModifiedDate < {ts'@{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-dd HH:mm:ss')}'}

Errore di MALFORMED_QUERY: troncato

Se si verifica l'errore "MALFORMED_QUERY: troncato", in genere il problema è dovuto alla presenza di una colonna di tipo JunctionIdList nei dati e Salesforce ha limitazioni sul supporto di tali dati con un numero elevato di righe. Per attenuare il problema, provare a escludere la colonna JunctionIdList o limitare il numero di righe da copiare. È possibile partizionare in più esecuzioni di attività di copia.

Mapping dei tipi di dati per Salesforce

Quando si copiano dati da Salesforce, vengono usati i mapping seguenti tra i tipi di dati di Salesforce e i tipi di dati provvisori internamente al servizio. Per informazioni su come l'attività di copia esegue il mapping dello schema di origine e del tipo di dati al sink, vedere Mapping dello schema e del tipo di dati.

Tipo di dati di Salesforce	Tipo di dati provvisorio del servizio
Numerazione automatica	String
Casella di controllo	Booleano
Valuta	Decimale
Data	Data/Ora
Data/ora	Data/Ora
Indirizzo e-mail	String
ID	String
Relazione di ricerca	String
Elenco a discesa seleziona multipla	String
Numero	Decimali
Percentuale	Decimale
Telefono	String
Picklist	String
Testo	String
Area testo.	String
Area di testo (Long)	String
Area di testo (Rich)	String
Testo (Crittografato)	String
URL	String

Nota

Il tipo di numero Salesforce esegue il mapping al tipo Decimale nelle pipeline di Azure Data Factory e Azure Synapse come tipo di dati provvisorio del servizio. Il tipo Decimal rispetta la precisione e la scala definite. Per i dati le cui posizioni decimali superano la scala definita, il relativo valore verrà arrotondato nei dati di anteprima e nella copia. Per evitare di ottenere tali perdite di precisione nelle pipeline di Azure Data Factory e Azure Synapse, è consigliabile aumentare le posizioni decimali a un valore ragionevolmente elevato nella pagina Modifica definizione campo personalizzato di Salesforce.

Proprietà dell'attività Lookup

Per altre informazioni sulle proprietà, vedere Attività Lookup.

Passaggi successivi

Per un elenco degli archivi dati supportati come origini e sink dall'attività di copia, vedere Archivi dati supportati.

Condividi tramite

Copiare dati da e in Salesforce V1 usando Azure Data Factory o Azure Synapse Analytics

Funzionalità supportate

Prerequisiti

Limiti delle richieste Salesforce

Operazioni preliminari

Creare un servizio collegato a Salesforce tramite l'interfaccia utente

Dettagli di configurazione del connettore

Proprietà del servizio collegato

Proprietà del set di dati

Proprietà dell'attività di copia

Salesforce come tipo di origine

Salesforce come tipo di sink

Suggerimenti di query

Recuperare dati da un report di Salesforce

Recuperare i record eliminati dal Cestino di Salesforce

Differenza tra la sintassi di query SOQL e SQL

Recuperare i dati usando una clausola where nella colonna DateTime

Errore di MALFORMED_QUERY: troncato

Mapping dei tipi di dati per Salesforce

Proprietà dell'attività Lookup

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive