Aller au contenu

Salesforce : interroger un objet

Lit un objet Salesforce, standard ou personnalisé, dans une table de projet via Bulk API 2.0 de Salesforce. Choisissez la connexion Salesforce, l’objet et les champs ; l’étape construit la requête, pagine l’ensemble du jeu de résultats et charge chaque colonne avec le type que Salesforce déclare pour elle. Il n’y a aucune requête à écrire.

Salesforce est atteint en direct depuis le cloud via son API REST ; cette étape n’a donc besoin d’aucun agent PlaidLink.

Champ Obligatoire Remarques
Connexion Salesforce Oui La connexion Salesforce à utiliser pour la lecture. Les connexions se gèrent dans Tools > Connections.
Environnement Non Lequel des environnements de la connexion lire : dirigez un environnement de bac à sable vers l’organisation de bac à sable et un environnement de production vers la production. Environnement du projet (par défaut) utilise l’environnement de connexion du projet. Environnement fixe utilise toujours celui que vous choisissez. Voir Fixer une étape à un environnement.
Objet Oui Le nom d’API de l’objet : Account, Opportunity, Invoice__c. Le sélecteur répertorie les objets que l’utilisateur d’exécution de la connexion peut interroger, et accepte aussi un nom saisi, de sorte qu’une étape enregistrée continue de fonctionner lorsque la détection est indisponible.
Table cible Oui La table de projet dans laquelle les lignes sont chargées.
Inclure les enregistrements supprimés et archivés Non Lit aussi les enregistrements de la corbeille et les activités archivées, comme le fait un queryAll de Salesforce.
Champs Oui Cochez les champs à extraire. Au moins un est obligatoire : Bulk API 2.0 rejette une sélection d’objet entier, donc la liste des colonnes est toujours énumérée.
Filtre Non Restreint l’extraction dans Salesforce. Consultez Filtrer dans Salesforce.
Étiquette de fenêtre Non Nomme la fenêtre d’extraction. Consultez Les fenêtres d’extraction ne s’exécutent qu’une fois.

Id est toujours inclus, que vous le cochiez ou non : c’est la clé sur laquelle chaque réexécution fusionne. Un champ de devise récupère aussi son CurrencyIsoCode lorsque l’objet en possède un.

Aperçu dans l’onglet Source affiche jusqu’à 100 lignes de ce que l’étape lirait, sans l’exécuter. Les variables du filtre sont renseignées comme le fait une exécution, mais les formats de variables comme {x:>9} ne sont pas pris en charge. L’aperçu n’est pas disponible sur un projet verrouillé. Si le filtre utilise un élément que l’aperçu ne peut pas vérifier comme étant en lecture seule, il vous indique d’exécuter l’étape.

Chaque exécution lit l’objet en entier, sous réserve de votre filtre, et fusionne chaque page dans la table cible sur Id. Une ligne déjà présente dans la table est remplacée sur place ; une exécution interrompue qui reprend ne recharge donc rien en double.

Les colonnes chargées utilisent les types que Salesforce déclare dans ses propres métadonnées de champs, jamais un type deviné à partir de la première page de données. La colonne Chargé comme du sélecteur de champs est ce type déclaré ; la forme que vous approuvez dans le formulaire est donc celle que reçoit la table.

Type de champ Salesforce Chargé comme
id, reference, string, textarea, phone, url, email, picklist, multipicklist, combobox texte
boolean booléen
date date
datetime horodatage
time heure
int entier, ou entier sur 64 bits lorsque le champ déclare 10 chiffres ou plus
double, currency, percent numérique : un décimal large, 38 chiffres dont 10 décimales

Trois conventions découlent de ce tableau et méritent d’être connues avant de bâtir quoi que ce soit sur la sortie :

  • La devise est chargée comme un nombre, et non comme un type devise. Les organisations réelles déclarent des champs de devise avec des échelles de 0, 2, 3 et 4 ; chaque type numérique est donc chargé dans un décimal assez large pour tous. La colonne n’a aucun symbole monétaire ni contrainte de décimales par champ. Lorsque l’objet porte CurrencyIsoCode, cette colonne accompagne le champ de devise afin que le montant conserve sa devise ; une organisation à devise unique n’a pas ce champ sur l’objet, et aucun n’est inventé.
  • Un pourcentage est le nombre entier que rapporte Salesforce. 20 signifie 20 pour cent, et non 0.2. Rien n’est remis à l’échelle à l’entrée.
  • Une valeur vide est chargée comme NULL. Les résultats en masse ne peuvent pas distinguer un véritable null d’une chaîne vide explicite ; les deux sont donc chargés comme NULL, dans chaque colonne, texte compris. Une colonne qui doit conserver la sémantique de la chaîne vide nécessite un champ de formule côté Salesforce.

Certains types de champs Salesforce ne peuvent pas être chargés fidèlement ; le sélecteur de champs les marque donc comme inutilisables et en indique la raison plutôt que de vous laisser enregistrer une étape qui échoue à l’exécution. Chaque refus nomme le champ et son type Salesforce.

Type de champ Salesforce Raison Que faire à la place
address, location (champs composés) Un champ composé n’a aucune valeur directement lisible dans une requête Bulk. Cochez ses champs composants : BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry, ainsi que la latitude et la longitude de la géolocalisation. Le sélecteur nomme les composants du champ que vous avez sous les yeux.
base64 Le contenu de fichier et de blob n’est jamais renvoyé en ligne ; il nécessite un téléchargement binaire distinct que cette étape n’effectue pas. Lisez les autres champs de l’enregistrement et traitez les pièces jointes séparément.
encryptedstring Salesforce renvoie une valeur masquée plutôt qu’une erreur lorsque l’utilisateur d’exécution n’a pas View Encrypted Data, et rien ne distingue des données masquées de données réelles. Charger silencieusement des lignes d’astérisques est pire que refuser. Décidez délibérément si les données doivent quitter Salesforce ; il n’existe aucun moyen pris en charge de les extraire via cette étape.
anyType Le type réel peut différer d’une ligne à l’autre, alors qu’une colonne de table n’a qu’un seul type. Extrayez un champ typé, ou un champ de formule qui rend la valeur sous forme de texte.
Tout type que l’étape ne reconnaît pas Refusé plutôt que chargé comme texte, ce qui changerait discrètement la signification de la valeur. Signalez-le à l’assistance afin que le type reçoive un mappage.

Les fenêtres d’extraction ne s’exécutent qu’une fois

Section intitulée « Les fenêtres d’extraction ne s’exécutent qu’une fois »

Étiquette de fenêtre nomme la fenêtre de données qu’une exécution charge : une période ou une étiquette de lot comme 2026-09. Elle accepte les variables de workflow : une étiquette {period} se résout en la valeur de cette variable à chaque exécution de l’étape.

Une fenêtre d’extraction ne s’exécute qu’une fois. Réexécuter une fenêtre déjà terminée ne retourne pas dans Salesforce : l’étape indique clairement qu’elle n’a pas relu les données, et précise que le nombre de lignes affiché appartient à l’exécution antérieure. C’est une absence d’opération bruyante, pas silencieuse, et c’est le comportement qui empêche une réexécution de paginer une seconde copie d’un jeu de résultats déjà chargé.

Il y a trois façons d’utiliser l’étape :

  • Laissez l’étiquette vide et traitez l’étape comme un chargement ponctuel. La première exécution lit ; une seconde exécution de cette même étape rejoue et signale qu’elle n’a pas relu. Utilisez ceci pour construire et valider l’extraction, et pour une table que vous chargez une seule fois.
  • Saisissez une étiquette et changez-la lorsque vous chargez la fenêtre suivante : 2026-09, puis 2026-10. Modifier l’étiquette démarre une nouvelle fenêtre, de sorte qu’un chargement mensuel que quelqu’un fait avancer à la main fonctionne exactement comme il se lit.
  • Construisez l’étiquette à partir d’une variable de workflow pour une extraction récurrente sans surveillance, par exemple {period}, définie par une étape antérieure du workflow sur la période en cours de chargement. Chaque exécution planifiée nomme sa propre fenêtre, et une réexécution au sein de la même période reprend ou rejoue cette fenêtre au lieu d’en démarrer une autre.

Un appelant de l’API REST ou de MCP transmet directement extract_tag et fournit lui-même une valeur distincte par fenêtre.

Une exécution interrompue reprend la même fenêtre ; conservez donc l’étiquette constante tant que cette fenêtre peut encore avoir besoin de se terminer. Changer l’étiquette démarre une nouvelle fenêtre et une nouvelle requête dans Salesforce. Changez l’étiquette chaque fois que vous changez le filtre ou les champs : modifier la configuration sous une étiquette déjà exécutée est refusé comme un conflit.

Restreignez l’extraction dans Salesforce plutôt que d’extraire tout l’objet puis de filtrer ensuite. Chaque terme de filtre est composé d’un champ, d’un opérateur et d’une valeur ; les termes se combinent avec AND. Une valeur peut utiliser une variable de workflow, comme {region}.

Opérateur Remarques
=, !=, <, <=, >, >= Comparés à la valeur telle que saisie.
LIKE Utilisez % comme caractère générique, par exemple Acme%.
IN, NOT IN Fournissez une liste de valeurs séparées par des virgules.

Le champ comme l’opérateur sont contrôlés par rapport aux champs que vous avez sélectionnés avant la construction de la requête, et il n’y a aucune clause WHERE en texte libre à écrire ; un filtre ne peut donc pas dépasser l’extraction. Filtrez sur un champ que vous avez aussi coché ; un filtre qui nomme un champ que l’extraction ne sélectionne pas est refusé.

L’étape n’offre ni limite de lignes ni tri. Bulk API 2.0 désactive son propre découpage interne lorsqu’une requête comporte l’un ou l’autre, ce qui ralentit une grande extraction et la rend plus susceptible d’expirer. Des critères de filtre sélectifs sont le remède propre à Salesforce pour une requête trop volumineuse ou trop lente.

Cette forme, qui lit l’objet en entier selon une planification, convient aux objets à volume modéré et à renouvellement modéré : Accounts, Opportunities, Leads, Campaigns et objets personnalisés de taille similaire.

Elle est inadaptée aux objets à fort volume et à fort renouvellement comme Task, EmailMessage ou un grand objet personnalisé dont des millions de lignes changent chaque jour. Une extraction complète nocturne de ceux-ci consomme du temps réel et de la capacité d’API qu’une synchronisation incrémentielle n’aurait pas consommés. Lorsque l’objet est volumineux mais que seule une partie présente de l’intérêt, un filtre qui borne l’extraction (une plage de dates, un type d’enregistrement, un propriétaire) la ramène à une extraction de volume modéré.

Ce que vous voyez Ce qui s’est passé Que faire
Une erreur indiquant que la tâche est toujours en cours après 15 minutes L’étape attend au premier plan que Salesforce termine la requête, et cette attente est bornée. Rien ne fait avancer la tâche en arrière-plan. L’étape échoue, de sorte que les étapes suivantes ne s’exécutent pas sur une table que cette extraction n’a pas écrite. Reprenez le workflow ou réexécutez l’étape. Elle reprend l’attente sur la même tâche Salesforce et n’en soumet jamais une seconde. Si elle dépasse régulièrement la limite, restreignez l’extraction avec des critères de filtre.
Un avertissement indiquant que la fenêtre est déjà terminée et n’a pas été relue La fenêtre a déjà été exécutée. Le nombre de lignes affiché est celui de l’exécution antérieure. Exécutez l’extraction avec une Étiquette de fenêtre distincte, ou faites avancer la variable à partir de laquelle l’étiquette est construite ; consultez Les fenêtres d’extraction ne s’exécutent qu’une fois.
Une erreur nommant une tâche en échec ou abandonnée Une tâche de requête Bulk en échec ne produit aucun résultat partiel et ne peut pas être reprise. La fenêtre est désormais épuisée. Réexécutez avec une Étiquette de fenêtre distincte. Réexécuter la même fenêtre rejoue l’échec et ne soumet rien, et modifier la configuration de l’étape sous la même étiquette est refusé comme un conflit.
Un refus nommant la limite de requêtes de Salesforce Le quota glissant de 24 heures de requêtes d’API de l’organisation est épuisé. Salesforce ne documente aucun délai de nouvelle tentative pour cela. Attendez que la fenêtre se libère, puis réexécutez : l’extraction est toujours reprenable, rien n’a été perdu.
Un refus nommant un champ et son type Salesforce Ce type de champ ne peut pas être chargé, ou l’utilisateur d’exécution ne peut pas lire le champ. Consultez Champs que l’étape refuse et la sécurité au niveau des champs de l’utilisateur d’exécution.

Salesforce conserve les résultats d’une tâche de requête terminée récupérables pendant 7 jours, ce qui rend une extraction interrompue reprenable, et ce qui borne le temps pendant lequel une reprise peut attendre avant que les résultats ne disparaissent. Les tâches sont visibles dans Salesforce sous Setup > Environments > Jobs > Bulk Data Load Jobs.