Copiare dati da e in Salesforce Service Cloud usando Azure Data FactoryCopy data from and to Salesforce Service Cloud by using Azure Data Factory

Questo articolo illustra come usare l'attività di copia in Azure Data Factory per copiare dati da e in Salesforce Service Cloud.This article outlines how to use Copy Activity in Azure Data Factory to copy data from and to Salesforce Service Cloud. Si basa sull'articolo di panoramica dell'attività di copia che presenta informazioni generali sull'attività di copia.It builds on the Copy Activity overview article that presents a general overview of the copy activity.

Funzionalità supportateSupported capabilities

Questo connettore Cloud del servizio Salesforce è supportato per le attività seguenti:This Salesforce Service Cloud connector is supported for the following activities:

È possibile copiare dati dal cloud del servizio Salesforce in qualsiasi archivio dati di sink supportato.You can copy data from Salesforce Service Cloud to any supported sink data store. È anche possibile copiare dati da qualsiasi archivio dati di origine supportato a Salesforce Service Cloud.You also can copy data from any supported source data store to Salesforce Service Cloud. Per un elenco degli archivi dati supportati come origini o sink dall'attività di copia, vedere la tabella relativa agli archivi dati supportati.For a list of data stores that are supported as sources or sinks by the Copy activity, see the Supported data stores table.

In particolare, il connettore Cloud del servizio salesforce supporta:Specifically, this Salesforce Service Cloud connector supports:

  • Le edizioni Developer, Professional, Enterprise o Unlimited di Salesforce.Salesforce Developer, Professional, Enterprise, or Unlimited editions.
  • La copia di dati da e nell'ambiente di produzione, nella sandbox e nel dominio personalizzato di Salesforce.Copying data from and to Salesforce production, sandbox, and custom domain.

Il connettore Cloud del servizio Salesforce è basato sull'API REST/bulk di Salesforce, con V45 per la copia dei dati da e V40 per la copia dei dati in.The Salesforce Service Cloud connector is built on top of the Salesforce REST/Bulk API, with v45 for copy data from and v40 for copy data to.

PrerequisitiPrerequisites

In Salesforce deve essere abilitata l'autorizzazione API.API permission must be enabled in Salesforce. 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).For more information, see Enable API access in Salesforce by permission set

Limiti delle richieste SalesforceSalesforce request limits

Salesforce presenta limiti per le richieste API totali e per le richieste API simultanee.Salesforce has limits for both total API requests and concurrent API requests. Tenere presente quanto segue:Note the following points:

  • Se il numero di richieste simultanee supera il limite, si verifica una limitazione e vengono visualizzati errori casuali.If the number of concurrent requests exceeds the limit, throttling occurs and you see random failures.
  • Se il numero totale di richieste supera il limite, l'account di Salesforce viene bloccato per 24 ore.If the total number of requests exceeds the limit, the Salesforce account is blocked for 24 hours.

In entrambi gli scenari è anche possibile che venga visualizzato il messaggio di errore "REQUEST_LIMIT_EXCEEDED" ("LIMITE_RICHIESTE_SUPERATO").You might also receive the "REQUEST_LIMIT_EXCEEDED" error message in both scenarios. Per altre informazioni, vedere la sezione "API Request Limits" (Limiti delle richieste API) in Salesforce developer limits (Limiti per sviluppatori di Salesforce).For more information, see the "API request limits" section in Salesforce developer limits.

Attività inizialiGet started

È possibile usare l'attività di copia con una pipeline tramite uno degli strumenti o degli SDK seguenti.You can use one of the following tools or SDKs to use the copy activity with a pipeline. Per istruzioni dettagliate, selezionare un collegamento:Select a link for step-by-step instructions:

Le sezioni seguenti riportano informazioni dettagliate sulle proprietà che vengono usate per definire Data Factory entità specifiche del connettore del servizio cloud di Salesforce.The following sections provide details about properties that are used to define Data Factory entities specific to the Salesforce Service Cloud connector.

Proprietà del servizio collegatoLinked service properties

Per il servizio collegato di Salesforce sono supportate le proprietà seguenti.The following properties are supported for the Salesforce linked service.

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà Type deve essere impostata su SalesforceServiceCloud.The type property must be set to SalesforceServiceCloud. Yes
environmentUrlenvironmentUrl Specificare l'URL dell'istanza di Salesforce Service Cloud.Specify the URL of the Salesforce Service Cloud instance.
- Il valore predefinito è "https://login.salesforce.com".- Default is "https://login.salesforce.com".
- Per copiare dati dalla sandbox, specificare "https://test.salesforce.com".- To copy data from sandbox, specify "https://test.salesforce.com".
- Per copiare dati dal dominio personalizzato, specificare ad esempio "https://[domain].my.salesforce.com".- To copy data from custom domain, specify, for example, "https://[domain].my.salesforce.com".
NoNo
usernameusername Specificare un nome utente per l'account utente.Specify a user name for the user account. Yes
passwordpassword Specificare la password per l'account utente.Specify a password for the user account.

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.Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault.
Yes
securityTokensecurityToken Specificare un token di sicurezza per l'account utente.Specify a security token for the user account. Per istruzioni su come reimpostare o ottenere un token di sicurezza, vedere Get a security token (Ottenere un token di sicurezza).For instructions on how to reset and get a security token, see Get a security token. Per informazioni generali sui token di sicurezza, vedere Security and the API(Sicurezza e API).To learn about security tokens in general, see Security and the API.

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.Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault.
Yes
connectViaconnectVia Runtime di integrazione da usare per la connessione all'archivio dati.The integration runtime to be used to connect to the data store. Se non specificato, viene usato il runtime di integrazione di Azure predefinito.If not specified, it uses the default Azure Integration Runtime. No per l'origine, Sì per il sink se il servizio collegato all'origine non dispone di un runtime di integrazioneNo for source, Yes for sink if the source linked service doesn't have integration runtime

Importante

Quando si copiano dati in Salesforce Service Cloud, non è possibile usare il Azure Integration Runtime predefinito per eseguire la copia.When you copy data into Salesforce Service Cloud, the default Azure Integration Runtime can't be used to execute copy. In altre parole, se il servizio collegato all'origine non dispone di un runtime di integrazione specifico, creare in modo esplicito un Azure Integration Runtime con una posizione vicina all'istanza del cloud del servizio salesforce.In other words, if your source linked service doesn't have a specified integration runtime, explicitly create an Azure Integration Runtime with a location near your Salesforce Service Cloud instance. Associare il servizio collegato del cloud del servizio Salesforce come nell'esempio seguente.Associate the Salesforce Service Cloud linked service as in the following example.

Esempio: Archiviare le credenziali in Data FactoryExample: Store credentials 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 VaultExample: Store credentials 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 datiDataset properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere l'articolo Set di dati.For a full list of sections and properties available for defining datasets, see the Datasets article. Questa sezione presenta un elenco delle proprietà supportate dal set di dati del servizio Salesforce Service Cloud.This section provides a list of properties supported by the Salesforce Service Cloud dataset.

Per copiare dati da e in Salesforce Service Cloud, sono supportate le proprietà seguenti.To copy data from and to Salesforce Service Cloud, the following properties are supported.

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà Type deve essere impostata su SalesforceServiceCloudObject.The type property must be set to SalesforceServiceCloudObject. Yes
objectApiNameobjectApiName Nome dell'oggetto di Salesforce da cui recuperare i dati.The Salesforce object name to retrieve data from. No per l'origine, Sì per il sinkNo for source, Yes for sink

Importante

La parte "__c" delnome dell'API è necessaria per qualsiasi oggetto personalizzato.The "__c" part of API Name is needed for any custom object.

Nome API della connessione Salesforce di Data Factory

Esempio:Example:

{
    "name": "SalesforceServiceCloudDataset",
    "properties": {
        "type": "SalesforceServiceCloudObject",
        "typeProperties": {
            "objectApiName": "MyTable__c"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Salesforce Service Cloud linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}
ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type del set di dati deve essere impostata su RelationalTable.The type property of the dataset must be set to RelationalTable. Yes
tableNametableName Nome della tabella in Salesforce Service Cloud.Name of the table in Salesforce Service Cloud. No (se nell'origine dell'attività è specificato "query")No (if "query" in the activity source is specified)

Proprietà dell'attività di copiaCopy activity properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline.For a full list of sections and properties available for defining activities, see the Pipelines article. Questa sezione presenta un elenco delle proprietà supportate dall'origine e dal sink del servizio salesforce.This section provides a list of properties supported by Salesforce Service Cloud source and sink.

Cloud del servizio Salesforce come tipo di origineSalesforce Service Cloud as a source type

Per copiare dati da Salesforce Service Cloud, nella sezione origine dell'attività di copia sono supportate le proprietà seguenti.To copy data from Salesforce Service Cloud, the following properties are supported in the copy activity source section.

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà Type dell'origine dell'attività di copia deve essere impostata su SalesforceServiceCloudSource.The type property of the copy activity source must be set to SalesforceServiceCloudSource. Yes
queryquery Usare la query personalizzata per leggere i dati.Use the custom query to read data. È possibile usare una query SQL-92 o una query Salesforce Object Query Language (SOQL).You can use Salesforce Object Query Language (SOQL) query or SQL-92 query. Vedere altri suggerimenti nella sezione Suggerimenti di query.See more tips in query tips section. Se la query non è specificata, verranno recuperati tutti i dati dell'oggetto Cloud del servizio salesforce specificato in "objectApiName" nel set di dati.If query is not specified, all the data of the Salesforce Service Cloud object specified in "objectApiName" in dataset will be retrieved. No (se "objectApiName" è specificato nel set di dati)No (if "objectApiName" in the dataset is specified)
readBehaviorreadBehavior Indica se eseguire query sui record esistenti o su tutti i record inclusi quelli eliminati.Indicates whether to query the existing records, or query all records including the deleted ones. Se non specificato, il comportamento predefinito è quello indicato per primo.If not specified, the default behavior is the former.
Valori consentiti: query (predefinito), queryAll.Allowed values: query (default), queryAll.
NoNo

Importante

La parte "__c" delnome dell'API è necessaria per qualsiasi oggetto personalizzato.The "__c" part of API Name is needed for any custom object.

Elenco dei nomi API della connessione Salesforce di Data Factory

Esempio:Example:

"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 del servizio Salesforce come tipo di sinkSalesforce Service Cloud as a sink type

Per copiare dati in Salesforce Service Cloud, nella sezione sink dell'attività di copia sono supportate le proprietà seguenti.To copy data to Salesforce Service Cloud, the following properties are supported in the copy activity sink section.

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà Type del sink dell'attività di copia deve essere impostata su SalesforceServiceCloudSink.The type property of the copy activity sink must be set to SalesforceServiceCloudSink. Yes
writebehaviorwriteBehavior Comportamento dell'azione di scrittura per l'operazione.The write behavior for the operation.
I valori consentiti sono: Insert e Upsert.Allowed values are Insert and Upsert.
No (il valore predefinito è Insert)No (default is Insert)
externalIdFieldNameexternalIdFieldName Nome del campo ID esterno per l'operazione upsert.The name of the external ID field for the upsert operation. Il campo specificato deve essere definito come "campo ID esterno" nell'oggetto Cloud del servizio salesforce.The specified field must be defined as "External Id Field" in the Salesforce Service Cloud object. Non può includere valori NULL nei dati di input corrispondenti.It can't have NULL values in the corresponding input data. Sì per "Upsert"Yes for "Upsert"
writeBatchSizewriteBatchSize Conteggio delle righe dei dati scritti in Salesforce Service Cloud in ogni batch.The row count of data written to Salesforce Service Cloud in each batch. No (il valore predefinito è 5.000)No (default is 5,000)
ignoreNullValuesignoreNullValues Indica se ignorare i valori NULL dai dati di input durante un'operazione di scrittura.Indicates whether to ignore NULL values from input data during a write operation.
I valori consentiti sono true e false.Allowed values are true and false.
- True: i dati nell'oggetto di destinazione rimangono invariati quando si esegue un'operazione di upsert o aggiornamento.- True: Leave the data in the destination object unchanged when you do an upsert or update operation. Inserire un valore predefinito definito quando si esegue un'operazione di inserimento.Insert a defined default value when you do an insert operation.
- False: i dati nell'oggetto di destinazione vengono aggiornati a NULL quando si esegue un'operazione di upsert o aggiornamento.- False: Update the data in the destination object to NULL when you do an upsert or update operation. Inserire un valore NULL quando si esegue un'operazione di inserimento.Insert a NULL value when you do an insert operation.
No (il valore predefinito è false)No (default is false)

Esempio:Example:

"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 queryQuery tips

Recuperare dati da un report cloud di servizio salesforceRetrieve data from a Salesforce Service Cloud report

È possibile recuperare dati dai report cloud del servizio salesforce specificando una query {call "<report name>"}come.You can retrieve data from Salesforce Service Cloud reports by specifying a query as {call "<report name>"}. Un esempio è "query": "{call \"TestReport\"}".An example is "query": "{call \"TestReport\"}".

Recuperare i record eliminati dal cestino del servizio salesforceRetrieve deleted records from the Salesforce Service Cloud Recycle Bin

Per eseguire una query sui record eliminati temporaneamente dal cestino del servizio Salesforce, è possibile specificare readBehavior come. queryAllTo query the soft deleted records from the Salesforce Service Cloud Recycle Bin, you can specify readBehavior as queryAll.

Differenza tra la sintassi di query SOQL e SQLDifference between SOQL and SQL query syntax

Quando si copiano dati da Salesforce Service Cloud, è possibile usare query SOQL o query SQL.When copying data from Salesforce Service Cloud, you can use either SOQL query or SQL query. Si noti che queste due query hanno una sintassi e un supporto di funzionalità diversi. Non mischiarli.Note that these two has different syntax and functionality support, do not mix it. Si consiglia di usare la query SOQL, supportata in modo nativo da Salesforce Service Cloud.You are suggested to use the SOQL query which is natively supported by Salesforce Service Cloud. Nella tabella seguente sono elencate le differenze principali:The following table lists the main differences:

SintassiSyntax Modalità SOQLSOQL Mode Modalità SQLSQL Mode
Selezione di colonneColumn selection È necessario enumerare i campi da copiare nella query, ad esempioSELECT field1, filed2 FROM objectnameNeed to enumerate the fields to be copied in the query, e.g. SELECT field1, filed2 FROM objectname SELECT * è supportata oltre alla selezione della colonna.SELECT * is supported in addition to column selection.
VirgoletteQuotation marks I nomi di campo/oggetto non possono essere racchiusi tra virgolette.Filed/object names cannot be quoted. I nomi di campo/oggetto non possono essere racchiusi tra virgolette, ad es. SELECT "id" FROM "Account"Field/object names can be quoted, e.g. SELECT "id" FROM "Account"
Formato DatetimeDatetime format Fare riferimento a informazioni dettagliate qui ed esempi nella sezione successiva.Refer to details here and samples in next section. Fare riferimento a informazioni dettagliate qui ed esempi nella sezione successiva.Refer to details here and samples in next section.
Valori booleaniBoolean values Rappresentati come False e True, ad esempio SELECT … WHERE IsDeleted=True.Represented as False and True, e.g. SELECT … WHERE IsDeleted=True. Rappresentati come 0 o 1, ad esempio SELECT … WHERE IsDeleted=1.Represented as 0 or 1, e.g. SELECT … WHERE IsDeleted=1.
Ridenominazione delle colonneColumn renaming Non supportati.Not supported. Supportata, ad es. SELECT a AS b FROM ….Supported, e.g.: SELECT a AS b FROM ….
RelazioneRelationship Supportata, ad es. Account_vod__r.nvs_Country__c.Supported, e.g. Account_vod__r.nvs_Country__c. Non supportati.Not supported.

Recuperare i dati usando una clausola where nella colonna DateTimeRetrieve data by using a where clause on the DateTime column

Quando si specifica la query SOQL o SQL, prestare attenzione alla differenza di formato di DateTime.When you specify the SOQL or SQL query, pay attention to the DateTime format difference. Ad esempio:For example:

  • 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')}SOQL sample: 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')}'}SQL sample: 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: troncatoError of MALFORMED_QUERY:Truncated

Se viene raggiunto l'errore "MALFORMED_QUERY: Troncato ", in genere è dovuto alla presenza di una colonna di tipo JunctionIdList nei dati e a Salesforce è possibile limitare il supporto di tali dati con un numero elevato di righe.If you hit error of "MALFORMED_QUERY: Truncated", normally it's due to you have JunctionIdList type column in data and Salesforce has limitation on supporting such data with large number of rows. Per attenuare, provare a escludere la colonna JunctionIdList o a limitare il numero di righe da copiare (è possibile partizionare in più esecuzioni di attività di copia).To mitigate, try to exclude JunctionIdList column or limit the number of rows to copy (you can partition to multiple copy activity runs).

Mapping dei tipi di dati per Salesforce Service CloudData type mapping for Salesforce Service Cloud

Quando si copiano dati da Salesforce Service Cloud, vengono usati i mapping seguenti dai tipi di dati del servizio Salesforce per Data Factory tipi di dati provvisori.When you copy data from Salesforce Service Cloud, the following mappings are used from Salesforce Service Cloud data types to Data Factory interim data types. 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.To learn about how the copy activity maps the source schema and data type to the sink, see Schema and data type mappings.

Tipo di dati cloud del servizio salesforceSalesforce Service Cloud data type Tipo di dati provvisorio di Data FactoryData Factory interim data type
Auto NumberAuto Number StringString
CheckboxCheckbox BooleanBoolean
CurrencyCurrency DecimalDecimal
DateDate DateTimeDateTime
Data/oraDate/Time DateTimeDateTime
EmailEmail StringString
IDId StringString
Relazione di ricercaLookup Relationship StringString
Elenco a discesa seleziona multiplaMulti-Select Picklist StringString
NumberNumber DecimalDecimal
PercentPercent DecimalDecimal
TelefonoPhone StringString
Elenco a discesaPicklist StringString
TextText StringString
Area di testoText Area StringString
Area di testo (Long)Text Area (Long) StringString
Area di testo (Rich)Text Area (Rich) StringString
Testo (Crittografato)Text (Encrypted) StringString
URLURL StringString

Proprietà attività di ricercaLookup activity properties

Per informazioni dettagliate sulle proprietà, controllare l' attività di ricerca.To learn details about the properties, check Lookup activity.

Passaggi successiviNext steps

Per un elenco degli archivi dati supportati come origini e sink dall'attività di copia in Data Factory, vedere gli archivi dati supportati.For a list of data stores supported as sources and sinks by the copy activity in Data Factory, see Supported data stores.