Copiare dati da e nel cloud del servizio Salesforce usando Azure Data Factory o Synapse Analytics (legacy)

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 illustra come usare l'attività di copia nelle pipeline di Azure Data Factory e Synapse Analytics per copiare dati da e nel cloud di Salesforce Service. Si basa sull'articolo di panoramica dell'attività di copia che presenta informazioni generali sull'attività di copia.

Importante

Il nuovo connettore cloud salesforce Service offre un supporto per il cloud di Salesforce Service nativo migliorato. Se si usa il connettore cloud salesforce Service legacy nella soluzione, aggiornare il connettore Cloud di Salesforce Service prima del 11 ottobre 2024. Per informazioni dettagliate sulla differenza tra la versione legacy e quella più recente, vedere questa sezione .

Funzionalità supportate

Questo connettore cloud salesforce Service è supportato per le funzionalità seguenti:

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

(1) Runtime di integrazione di Azure (2) Runtime di integrazione self-hosted

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

In particolare, questo connettore cloud salesforce Service 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.

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

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. Notare i punti seguenti:

• 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:

• Strumento Copia dati
• Il portale di Azure
• .NET SDK
• The Python SDK
• Azure PowerShell
• The REST API
• Modello di Azure Resource Manager

Creare un servizio collegato al cloud di Salesforce Service usando l'interfaccia utente

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

1. 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

   

2. Cercare Salesforce e selezionare Salesforce Service Cloud Connector.

   

3. Configurare i dettagli del servizio, testare la connessione e creare il nuovo servizio collegato.

   

Dettagli di configurazione di Connessione or

Le sezioni seguenti forniscono informazioni dettagliate sulle proprietà usate per definire entità di Data Factory specifiche del connettore cloud salesforce Service.

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 SalesforceServiceCloud.	Sì
environmentUrl	Specificare l'URL dell'istanza cloud di Salesforce Service. - 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 o 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 IR, fare riferimento agli indirizzi IP del runtime di integrazione di Azure. 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 in Azure Data Factory oppure fare riferimento a un segreto archiviato in Azure Key Vault.	No
apiVersion	Specificare la versione dell'API REST/Bulk di Salesforce da usare, ad esempio 48.0. Per impostazione predefinita, il connettore usa v45 per copiare dati da Salesforce e usa v40 per copiare i dati in Salesforce.	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": "SalesforceServiceCloudLinkedService",
    "properties": {
        "type": "SalesforceServiceCloud",
        "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": "SalesforceServiceCloudLinkedService",
    "properties": {
        "type": "SalesforceServiceCloud",
        "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"
        }
    }
}

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 fornisce un elenco delle proprietà supportate dal set di dati Salesforce Service Cloud.

Per copiare dati da e in Salesforce Service Cloud, sono supportate le proprietà seguenti.

Proprietà	Descrizione	Richiesto
type	La proprietà type deve essere impostata su SalesforceServiceCloudObject.	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.

Esempio:

{
    "name": "SalesforceServiceCloudDataset",
    "properties": {
        "type": "SalesforceServiceCloudObject",
        "typeProperties": {
            "objectApiName": "MyTable__c"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Salesforce Service Cloud linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Proprietà	Descrizione	Richiesto
type	La proprietà type del set di dati deve essere impostata su RelationalTable.	Sì
tableName	Nome della tabella in Salesforce Service Cloud.	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. In questa sezione viene fornito un elenco delle proprietà supportate dall'origine e dal sink di Salesforce Service Cloud.

Salesforce Service Cloud come tipo di origine

Per copiare dati da Salesforce Service Cloud, nella sezione origine 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 SalesforceServiceCloudSource.	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 query non viene specificata, verranno recuperati tutti i dati dell'oggetto Cloud salesforce Service specificato in "objectApiName" nel set di dati.	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.

Esempio:

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

Nota

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

Salesforce Service Cloud come tipo di sink

Per copiare i dati in Salesforce Service Cloud, 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 SalesforceServiceCloudSink.	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 "Campo ID esterno" nell'oggetto Cloud salesforce Service. Non può includere valori NULL nei dati di input corrispondenti.	Sì per "Upsert"
writeBatchSize	Numero di righe di dati scritti nel cloud del servizio 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)
maxConcurrent Connessione ions	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:

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

Suggerimenti di query

Recuperare dati da un report cloud di Salesforce Service

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

Recuperare i record eliminati dal Cestino cloud di Salesforce Service

Per eseguire una query sui record eliminati soft dal Cestino cloud di Salesforce Service, è possibile specificare readBehavior come queryAll.

Differenza tra la sintassi di query SOQL e SQL

Quando si copiano dati da Salesforce Service Cloud, è possibile usare query SOQL o query 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 Service Cloud. 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 è 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 ad 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 Service Cloud

Quando si copiano dati dal cloud di Salesforce Service, i mapping seguenti vengono usati dai tipi di dati cloud di Salesforce Service ai tipi di dati provvisori usati internamente all'interno del 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 Cloud di Salesforce Service	Tipo di dati provvisori 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 cloud del servizio Salesforce esegue il mapping al tipo Decimal in Azure Data Factory e nelle pipeline di Azure Synapse come tipo di dati provvisorio del servizio. Il tipo decimale 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 del cloud di Salesforce Service.

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.