Copiare dati da e in Salesforce usando Azure Data Factory

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

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

Funzionalità supportate

Questo connettore Salesforce è supportato per le attività seguenti:

È possibile copiare dati da Salesforce in qualsiasi archivio dati di sink supportato. È anche possibile copiare dati da qualsiasi archivio di dati di origine supportato in Salesforce. Per un elenco degli archivi dati supportati come origini o sink dal attività Copy, 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.

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 tra 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 la versione 40 dell'API bulk. È anche possibile impostare in modo esplicito la versione dell'API usata per leggere/scrivere dati tramite apiVersion la 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. 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).

Introduzione

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

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

Proprietà del servizio collegato

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

Proprietà Descrizione Obbligatoria
type La proprietà type deve essere impostata su Salesforce.
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.
password Specificare la password per l'account utente.

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.
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 del Integration Runtime all'elenco di indirizzi IP attendibili in Salesforce. Quando si Azure IR, fare riferimento Azure Integration Runtime indirizzi IP.

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 i dati da Salesforce e usa la versione 40 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 in Data Factory

{
    "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"
        }
    }
}

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 Obbligatoria
type La proprietà type deve essere impostata su SalesforceObject.
objectApiName Nome dell'oggetto di Salesforce da cui recuperare i dati. No per l'origine, Sì per il sink

Importante

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

Nome API della connessione Salesforce di Data Factory

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 Obbligatoria
type La proprietà type del set di dati deve essere impostata su RelationalTable.
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 Obbligatoria
type La proprietà type dell'origine dell'attività di copia deve essere impostata su SalesforceSource.
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" del nome dell'API è necessaria per qualsiasi oggetto personalizzato.

Elenco dei nomi API della connessione Salesforce di Data Factory

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

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 Obbligatoria
type La proprietà type del sink dell'attività di copia deve essere impostata su SalesforceSink.
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 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 superiore 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 supportata. Supportata, ad es. SELECT a AS b FROM ….
Relazione Supportata, ad es. Account_vod__r.nvs_Country__c. Non supportata.

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

Se si verifica l'errore "MALFORMED_QUERY: Truncated", in genere è dovuto alla colonna di tipo JunctionIdList nei dati e a Salesforce è associato un limite per il 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 eseguire il partizionamento in più esecuzioni dell'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 di Data Factory. 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 di Data Factory
Numero automatico Stringa
Casella di controllo Boolean
Valuta Decimal
Data Datetime
Data/ora Datetime
E-mail Stringa
ID Stringa
Relazione di ricerca Stringa
Elenco a discesa seleziona multipla Stringa
Numero Decimal
Percentuale Decimal
Telefono Stringa
Elenco a discesa Stringa
Testo Stringa
Area di testo Stringa
Area di testo (Long) Stringa
Area di testo (Rich) Stringa
Testo (Crittografato) Stringa
URL Stringa

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 in Data Factory, vedere gli archivi dati supportati.