Copiare dati da e in Salesforce Service Cloud usando Azure Data Factory

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

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

Funzionalità supportate

Salesforce Service Cloud Connector è supportato per le attività seguenti:

È possibile copiare dati da Salesforce Service Cloud in qualsiasi archivio dati sink supportato. È anche possibile copiare dati da qualsiasi archivio dati di origine supportato in Salesforce Service Cloud. Per un elenco degli archivi dati supportati come origini o sink dal attività Copy, vedere la tabella Archivi dati supportati.

In particolare, salesforce Service Cloud Connector 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. Per altre informazioni, vedere Enable API access in Salesforce by permission set (Abilitare l'accesso al'API in Salesforce in base al set di autorizzazioni).

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 forniscono informazioni dettagliate sulle proprietà che vengono usate per Data Factory entità specifiche di Salesforce Service Cloud Connector.

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 SalesforceServiceCloud.
environmentUrl Specificare l'URL dell'istanza di Salesforce Service Cloud.
- 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 la versione 45 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": "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. In questa sezione viene fornito 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 Obbligatoria
type La proprietà type deve essere impostata su SalesforceServiceCloudObject.
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&quot;: &quot;SalesforceServiceCloudDataset&quot;,
    &quot;properties&quot;: {
        &quot;type&quot;: &quot;SalesforceServiceCloudObject&quot;,
        &quot;typeProperties&quot;: {
            &quot;objectApiName&quot;: &quot;MyTable__c&quot;
        },
        &quot;schema&quot;: [],
        &quot;linkedServiceName&quot;: {
            &quot;referenceName&quot;: &quot;<Salesforce Service Cloud linked service name>&quot;,
            &quot;type&quot;: &quot;LinkedServiceReference&quot;
        }
    }
}
Proprietà Descrizione Obbligatoria
type La proprietà type del set di dati deve essere impostata su RelationalTable.
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 Obbligatoria
type La proprietà type dell'origine dell'attività di copia deve essere impostata su SalesforceServiceCloudSource.
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 Salesforce Service Cloud 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" del nome dell'API è necessaria per qualsiasi oggetto personalizzato.

Elenco dei nomi API della connessione Salesforce di Data Factory

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

Cloud di servizio Salesforce come tipo di sink

Per copiare dati in Salesforce Service Cloud, 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 SalesforceServiceCloudSink.
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 Service Cloud. Non può includere valori NULL nei dati di input corrispondenti. Sì per "Upsert"
writeBatchSize Numero di righe di dati scritti in Salesforce Service Cloud 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:

"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 di Salesforce Service Cloud

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

Recuperare i record eliminati da Salesforce Service Cloud Cestino

Per eseguire una query dei record eliminati automaticamente dal servizio Salesforce Service Cloud Cestino, è possibile specificare readBehavior come queryAll .

Differenza tra la sintassi di query SOQL e SQL

Quando si copiano dati da Salesforce Service Cloud, è possibile usare una query SOQL o una 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 supportata. Supportata, ad es. SELECT a AS b FROM ….
Relationship 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 al 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 Service Cloud

Quando si copiano dati da Salesforce Service Cloud, vengono usati i mapping seguenti dai tipi di dati di Salesforce Service Cloud Data Factory dati provvisori. 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 Salesforce Service Cloud Tipo di dati provvisorio di Data Factory
Numero automatico Stringa
Casella di controllo Boolean
Valuta Decimal
Data Datetime
Data/ora DataOra
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.