Copier des données de et vers Salesforce à l’aide d’Azure Data Factory ou d’Azure Synapse Analytics (hérité)

Article
01/30/2024

S’APPLIQUE À : Azure Data Factory Azure Synapse Analytics

Conseil

Essayez Data Factory dans Microsoft Fabric, une solution d’analyse tout-en-un pour les entreprises. Microsoft Fabric couvre tous les aspects, du déplacement des données à la science des données, en passant par l’analyse en temps réel, l’aide à la décision et la création de rapports. Découvrez comment démarrer un nouvel essai gratuitement !

Cet article décrit comment utiliser l’activité de copie dans des pipelines Azure Data Factory et Azure Synapse pour copier des données depuis et vers Salesforce Service Cloud. Il s’appuie sur l’article Vue d’ensemble de l’activité de copie.

Important

Le service a publié un nouveau connecteur Salesforce qui améliore la prise en charge native de Salesforce. Pour plus d’informations, consultez l’article Connecteur Salesforce.

Fonctionnalités prises en charge

Ce connecteur Salesforce est pris en charge pour les fonctionnalités suivantes :

Fonctionnalités prises en charge	IR
Activité de copie (source/récepteur)	① ②
Activité de recherche	① ②

① Runtime d’intégration Azure ② Runtime d’intégration auto-hébergé

Pour obtenir la liste des magasins de données pris en charge en tant que sources ou récepteurs, consultez la table Magasins de données pris en charge.

Ce connecteur Salesforce prend en charge :

Développeur Salesforce, éditions professionnelle, d’entreprise ou illimitées.
La copie de données depuis et vers le domaine de production, le bac à sable et le domaine personnalisé de Salesforce.

Notes

Cette fonction prend en charge la copie de n’importe quel schéma à partir des environnements Salesforce mentionnés ci-dessus, y compris le NPSP (Nonprofit Success Pack).

Le connecteur Salesforce est basé sur l'API REST/en bloc Salesforce. Lors de la copie de données depuis Salesforce, le connecteur choisit automatiquement entre les API REST et les API en bloc en fonction de la taille des données : lorsque le jeu de résultats est volumineux, l’API en bloc est utilisée pour de meilleures performances. Vous pouvez explicitement définir la version d’API utilisée pour lire/écrire des données par la propriété apiVersion du service lié. Lors de la copie de données dans Salesforce, le connecteur utilise l’API BULK v1.

Notes

Le connecteur ne définit plus la version par défaut de l’API Salesforce. Pour la compatibilité descendante, si une version d’API par défaut a été définie précédemment, elle continue à fonctionner. La valeur par défaut est 45.0 pour la source et 40.0 pour le récepteur.

Prérequis

L’autorisation de l’API doit être activée dans Salesforce.

Limites des requêtes Salesforce

Salesforce prend en charge un nombre limité de requêtes d’API totales et de requêtes d’API simultanées. Notez les points suivants :

Si le nombre de requêtes simultanées dépasse la limite autorisée, les nouvelles requêtes sont bloquées avec un risque de défaillances aléatoires.
Si le nombre total de requêtes dépasse la limite autorisée, le compte Salesforce est bloqué pendant 24 heures.

Vous pouvez également recevoir le message d’erreur « REQUEST_LIMIT_EXCEEDED » dans les deux scénarios. Pour plus d’informations, consultez la section « API Request Limits » (Limites de requête d’API) du document Salesforce Developer Limits (Limites des développeurs Salesforce).

Bien démarrer

Pour effectuer l’activité Copie avec un pipeline, vous pouvez vous servir de l’un des outils ou kits SDK suivants :

Créer un service lié à Salesforce à l’aide de l’interface utilisateur

Utilisez les étapes suivantes pour créer un service lié à Salesforce dans l’interface utilisateur du portail Azure.

Accédez à l’onglet Gérer dans votre espace de travail Azure Data Factory ou Synapse et sélectionnez Services liés, puis cliquez sur Nouveau :
- Azure Data Factory.
- Azure Synapse
Recherchez Salesforce et sélectionnez le connecteur Salesforce.
Configurez les informations du service, testez la connexion et créez le nouveau service lié.

Informations de configuration des connecteurs

Les sections suivantes fournissent des informations sur les propriétés utilisées pour définir des entités spécifiques au connecteur Salesforce.

Propriétés du service lié

Les propriétés suivantes sont prises en charge pour le service lié Salesforce :

Propriété	Description	Obligatoire
type	La propriété de type doit être définie sur Salesforce.	Oui
environmentUrl	Spécifiez l’URL de l’instance Salesforce. - La valeur par défaut est `"https://login.salesforce.com"`. - Pour copier des données du bac à sable, spécifiez `"https://test.salesforce.com"`. - Pour copier les données du domaine personnalisé, spécifiez, par exemple, `"https://[domain].my.salesforce.com"`.	Non
username	Spécifiez un nom d’utilisateur pour le compte d’utilisateur.	Oui
mot de passe	Spécifiez le mot de passe du compte d’utilisateur. Marquez ce champ en tant que SecureString afin de le stocker en toute sécurité, ou référencez un secret stocké dans Azure Key Vault.	Oui
securityToken	Spécifiez le jeton de sécurité du compte d’utilisateur. Pour en savoir plus sur les jetons de sécurité, consultez l’article Security and the API(Sécurité et API). Le jeton de sécurité peut être uniquement ignoré si vous ajoutez l’adresse IP d'Integration Runtime à la liste d'adresses IP approuvées sur Salesforce. Lorsque vous utilisez Azure IR, consultez Adresses IP Azure Integration Runtime. Pour des instructions sur l'obtention et la réinitialisation d’un jeton de sécurité, consultez l’article Obtenir un jeton de sécurité. Marquez ce champ en tant que SecureString afin de le stocker en toute sécurité, ou référencez un secret stocké dans Azure Key Vault.	Non
apiVersion	Spécifiez la version de l’API REST/en bloc de Salesforce à utiliser, par exemple `52.0`.	Non
connectVia	Le runtime d’intégration à utiliser pour se connecter à la banque de données. À défaut de spécification, le runtime d’intégration Azure par défaut est utilisé.	Non

Exemple : Stocker les informations d’identification

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

Exemple : Stocker les informations d’identification dans 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"
        }
    }
}

Exemple : Stocker les informations d’identification dans Key Vault, ainsi que environmentUrl et username

Notez qu’en procédant ainsi, vous ne pourrez plus utiliser l’interface utilisateur pour modifier les paramètres. La case à cocher Spécifier le contenu dynamique au format JSON sera cochée et vous devrez modifier cette configuration entièrement à la main. L’avantage est que vous pouvez dériver TOUS les paramètres de configuration du Key Vault au lieu de paramétrer tout autre élément ici.

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

Propriétés du jeu de données

Pour obtenir la liste complète des sections et propriétés disponibles pour la définition de jeux de données, consultez l’article Jeux de données. Cette section fournit la liste des propriétés prises en charge par le jeu de données Salesforce.

Pour copier des données depuis et vers Salesforce, définissez la propriété de type du jeu de données sur SalesforceObject. Les propriétés suivantes sont prises en charge.

Propriété	Description	Obligatoire
type	La propriété de type doit être définie sur SalesforceObject.	Oui
objectApiName	Nom d’objet Salesforce duquel extraire des données.	Non pour Source, Oui pour Récepteur

Important

La partie « __c » du nom de l’API est requise pour tout objet personnalisé.

Screenshot showing Salesforce connection API Name.

Exemple :

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

Notes

Pour la compatibilité descendante : Quand vous copiez des données depuis Salesforce, si vous utilisez le jeu de données de type « RelationalTable » précédent, il continue de fonctionner. Cependant, il vous est proposé de passer au nouveau type « SalesforceObject ».

Propriété	Description	Obligatoire
type	La propriété type du jeu de données doit être définie sur RelationalTable.	Oui
tableName	Nom de la table dans Salesforce.	Non (si « query » est spécifié dans la source de l’activité)

Propriétés de l’activité de copie

Pour obtenir la liste complète des sections et des propriétés disponibles pour la définition des activités, consultez l’article Pipelines. Cette section fournit la liste des propriétés prises en charge par la source et le récepteur Salesforce.

Salesforce en tant que type de source

Pour copier des données à partir de Salesforce, définissez le type de source sur SalesforceSource dans l’activité de copie. Les propriétés suivantes sont prises en charge dans la section source de l’activité de copie.

Propriété	Description	Obligatoire
type	La propriété de type de la source d’activité de copie doit être définie sur SalesforceSource.	Oui
query	Utilise la requête personnalisée pour lire des données. Vous pouvez utiliser une requête SQL-92 ou SOQL (Salesforce Object Query Language). Retrouvez d’autres conseils dans la section Conseils de requête. Si la requête n’est pas spécifiée, toutes les données de l’objet Salesforce spécifié au niveau de la propriété « objectApiName » du jeu de données seront récupérées.	Non (si « objectApiName » est spécifié dans le jeu de données)
readBehavior	Indique si seuls les enregistrements existants doivent être interrogés ou si tous les enregistrements, y compris ceux qui ont été supprimés, doivent être interrogés. Si rien n’est spécifié, le comportement par défaut appliqué est le premier. Valeurs autorisées : query (valeur par défaut), queryAll.	Non

Important

La partie « __c » du nom de l’API est requise pour tout objet personnalisé.

Screenshot showing Salesforce connection API Name list.

Exemple :

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

Notes

Pour la compatibilité descendante : Quand vous copiez des données depuis Salesforce, si vous utilisez le type « RelationalSource » précédent, la source continue de fonctionner. Cependant, il vous est proposé de passer au nouveau type « SalesforceSource ».

Notes

Contrairement au récepteur, la source Salesforce ne prend pas en charge les paramètres proxy dans le runtime d’intégration auto-hébergé.

Salesforce comme type de récepteur

Pour copier des données vers Salesforce, définissez le type de récepteur sur SalesforceSink dans l’activité de copie. Les propriétés suivantes sont prises en charge dans la section récepteur de l’activité de copie.

Propriété	Description	Obligatoire
type	La propriété de type du récepteur d’activité de copie doit être définie sur SalesforceSink.	Oui
writeBehavior	Comportement d’écriture de l’opération. Les valeurs autorisées sont Insert et Upsert.	Non (la valeur par défaut est un point Insert)
externalIdFieldName	Nom du champ ID externe pour l’opération upsert. Le champ spécifié doit être défini en tant que « Champ ID externe » dans l’objet Salesforce. Il ne peut pas avoir de valeurs NULL dans les données d’entrée correspondantes.	Oui, pour « Upsert »
writeBatchSize	Nombre de lignes de données écrites dans Salesforce pour chaque lot.	Non (valeur par défaut : 5,000)
ignoreNullValues	Indique si les valeurs NULL des données d’entrée doivent être ignorées pendant une opération d’écriture. Les valeurs autorisées sont true et false. - True : Conserver les données dans l’objet de destination quand vous effectuez une opération upsert ou de mise à jour. Insérer une valeur définie par défaut lorsque vous effectuez une opération insert. - False : Mettre à jour les données dans l’objet de destination avec la valeur NULL quand vous effectuez une opération upsert ou de mise à jour. Insérer une valeur NULL lorsque vous effectuez une opération insert.	Non (valeur par défaut : false)
maxConcurrentConnections	La limite supérieure de connexions simultanées établies au magasin de données pendant l’exécution de l’activité. Spécifiez une valeur uniquement lorsque vous souhaitez limiter les connexions simultanées.	Aucune

Exemple : Récepteur Salesforce dans une activité de copie

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

Conseils pour les requêtes

Récupérer des données à partir d’un rapport Salesforce

Vous pouvez récupérer des données à partir de rapports Salesforce en spécifiant une requête en tant que {call "<report name>"}. par exemple "query": "{call \"TestReport\"}".

Récupérer des enregistrements supprimés dans la Corbeille Salesforce

Pour interroger les enregistrements supprimés de manière réversible dans la Corbeille Salesforce, vous pouvez spécifier readBehaviorcomme queryAll.

Différence entre la syntaxe de requête SOQL et SQL

Lors de la copie des données à partir de Salesforce, vous pouvez utiliser une requête SOQL ou SQL. Ces deux requêtes ayant une syntaxe et une prise en charge des fonctionnalités différentes, ne les mélangez pas. Il est recommandé d’utiliser la requête SOQL, prise en charge nativement par Salesforce. Le tableau suivant répertorie les différences principales :

Syntaxe	Mode SOQL	Mode SQL
Sélection de colonnes	Besoin d'énumérer les champs à copier dans la requête, par exemple `SELECT field1, filed2 FROM objectname`	`SELECT *` est pris en charge en plus de la sélection de colonnes.
Guillemets	Les noms de champ ou d’objet ne peuvent pas être mis entre guillemets.	Les noms de champ ou d’objet peuvent être mis entre guillemets, par exemple `SELECT "id" FROM "Account"`
Format de date/heure	Reportez-vous aux détails ici et aux exemples fournis dans la section suivante.	Reportez-vous aux détails ici et aux exemples fournis dans la section suivante.
Valeurs booléennes	Représentées sous la forme de `False` et `True`, par exemple `SELECT … WHERE IsDeleted=True`.	Représenté sous la forme de 0 ou de 1, par exemple `SELECT … WHERE IsDeleted=1`.
Changement de nom de colonne	Non pris en charge.	Pris en charge, par exemple : `SELECT a AS b FROM …`.
Relation	Pris en charge, par exemple `Account_vod__r.nvs_Country__c`.	Non pris en charge.

Récupérer des données à l’aide d’une clause where sur la colonne DateTime

Lorsque vous spécifiez une requête SOQL ou SQL, faites attention à la différence de format DateTime. Par exemple :

Exemple 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')}
Exemple 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')}'}

Erreur MALFORMED_QUERY: Truncated

L'erreur « MALFORMED_QUERY: Truncated » peut être rencontrée lorsqu'une colonne de type JunctionIdList est présente dans les données et que la prise en charge par Salesforce de données contenant un grand nombre de lignes est limitée. Pour atténuer ce problème, essayez d'exclure la colonne JunctionIdList ou de limiter le nombre de lignes à copier (vous pouvez partitionner le travail en plusieurs exécutions d'activité de copie).

Mappage de type de données pour Salesforce

Lorsque vous copiez des données de Salesforce, les mappages suivants sont utilisés entre les types de données Salesforce et les types de données intermédiaires en interne dans le service. Pour découvrir comment l’activité de copie mappe le schéma et le type de données la source au récepteur, consultez Mappage de schéma dans l’activité de copie.

Type de données Salesforce	Type de données de service intermédiaire
Numérotation automatique	String
Case à cocher	Boolean
Devise	Decimal
Date	DateTime
Date/Heure	DateTime
Email	String
id	String
Relation de recherche	String
Liste déroulante à sélection multiple	String
Number	Decimal
Pourcentage	Decimal
Téléphone	String
Liste déroulante	String
Texte	String
Zone de texte	String
Zone de texte (long)	String
Zone de texte (enrichi)	String
Texte (chiffré)	String
URL	String

Notes

Le type numérique Salesforce est mappé au type décimal dans Azure Data Factory et les pipelines Azure Synapse en tant que type de données de service intermédiaire. Le type décimal respecte la précision et l’échelle définies. Pour les données dont le nombre de décimales dépasse l’échelle définie, leur valeur est arrondie dans les données d’aperçu et la copie. Pour éviter une telle perte de précision dans les pipelines Azure Data Factory et Azure Synapse, envisagez d’augmenter le nombre de décimales à une valeur raisonnablement importante dans la page Modification de la définition de champ personnalisé de Salesforce.

Propriétés de l’activité Lookup

Pour en savoir plus sur les propriétés, consultez Activité Lookup.

Étapes suivantes

Consultez les magasins de données pris en charge pour obtenir la liste des sources et magasins de données pris en charge en tant que récepteurs par l’activité de copie.

Share via

Copier des données de et vers Salesforce à l’aide d’Azure Data Factory ou d’Azure Synapse Analytics (hérité)

Fonctionnalités prises en charge

Prérequis

Limites des requêtes Salesforce

Bien démarrer

Créer un service lié à Salesforce à l’aide de l’interface utilisateur

Informations de configuration des connecteurs

Propriétés du service lié

Propriétés du jeu de données

Propriétés de l’activité de copie

Salesforce en tant que type de source

Salesforce comme type de récepteur

Conseils pour les requêtes

Récupérer des données à partir d’un rapport Salesforce

Récupérer des enregistrements supprimés dans la Corbeille Salesforce

Différence entre la syntaxe de requête SOQL et SQL

Récupérer des données à l’aide d’une clause where sur la colonne DateTime

Erreur MALFORMED_QUERY: Truncated

Mappage de type de données pour Salesforce

Propriétés de l’activité Lookup

Étapes suivantes

Ressources supplémentaires