Suivez votre progression
Accueil Trailhead
Accueil Trailhead

Utilisation de l’API SOAP

Objectifs de formation

Une fois cette unité terminée, vous pourrez :
  • Générer un fichier WSDL pour votre organisation
  • Utiliser SoapUI pour créer un projet SOAP à partir du fichier WSDL
  • Vous connecter à votre Trailhead Playground en utilisant l’API SOAP
  • Créer un compte en utilisant l’API SOAP

WSDL enterprise et partner

Si vous avez navigué dans les détroits d’une autre API basée sur SOAP, vous savez que le fichier WSDL (Web Services Description Language) est essentiellement une carte qui permet de comprendre l’utilisation de l’API. Elle contient les liaisons, les protocoles et les objets qui permettent d’effectuer des appels d’API.

Salesforce fournit deux fichiers WSDL pour l’API SOAP à utiliser dans deux scénarios différents. Le WSDL enterprise est optimisé pour une utilisation avec une seule organisation Salesforce. Il est fortement typé et reflète la configuration spécifique de votre organisation. Cela signifie que deux fichiers WSDL enterprise génèrent deux organisations distinctes qui contiennent des informations différentes.

Le WSDL partner est optimisé une utilisation avec de nombreuses organisations Salesforce. Il est faiblement typé et ne change pas en fonction de la configuration spécifique d’une organisation.

Généralement, lorsque vous écrivez une intégration pour une seule organisation Salesforce, vous utilisez le WSDL enterprise. Pour plusieurs organisations, vous utilisez le WSDL partner.

Dans cette unité, nous allons utiliser le WSDL enterprise pour explorer l’API SOAP. La première étape consiste à générer un fichier WSDL pour votre organisation. Dans votre Trailhead Playground, dans Configuration, saisissez « API » dans la case Recherche rapide, puis sélectionnez API. Dans la page API WSDL, cliquez sur Générer WSDL Enterprise.

Générer WDSL Entreprise

Dans la page Générer WDSL Entreprise, cliquez sur Generate. Une fois le WSDL généré, cliquez avec le bouton droit sur la page, puis enregistrez le fichier WSDL sur votre disque dur. Nous allons bientôt l’utiliser.

Voici un conseil pour travailler avec WSDL enterprise. Le WSDL enterprise reflète la configuration spécifique de votre organisation. Par conséquent, lorsque vous modifiez les métadonnées de votre organisation, générez un nouveau fichier WSDL. Ainsi, le fichier WSDL n’est pas en décalage avec la configuration de votre organisation.

Création d’un projet SOAP avec SoapUI

Maintenant que nous disposons de notre fichier WSDL, nous devons extraire ses informations pour commencer à envoyer des requêtes à l’API SOAP. En langage Web, ce processus est appelé consommation du WSDL. De la même façon qu’un Kraken consomme un bateau rempli de marins sans défense, des outils tels que WSC (Web Services Connector) consomment le fichier WSDL. Les outils créent ensuite des classes qui permettent d’exécuter des requêtes avec l’API SOAP en utilisant des langages de programmation courants.

Dans cette unité, nous allons utiliser un outil tiers appelé SoapUI pour consommer notre fichier WSDL enterprise. SoapUI est une application gratuite, de source ouverte, qui permet de tester les services Web. Pour commencer, téléchargez et installez SoapUI OpenSource depuis le site Web SoapUI. Installez uniquement le composant SoapUI.

Remarque

Remarque

Assurez-vous que la version de Java que SoapUI regroupe et utilise est compatible avec les politiques de sécurité de votre organisation. Vous pouvez trouver des informations sur la version de Java utilisée par SoapUI en sélectionnant Aide | Paramètres système depuis SoapUI.

Une fois SoapUI installé et lancé, dans le menu File, sélectionnez New SOAP Project. Pour le nom du projet, saisissez « Explorer l’API SOAP de Salesforce ». Pour le WSDL initial, accédez à l’emplacement où vous avez enregistré le fichier WSDL enterprise, puis sélectionnez-le. Laissez les autres options inchangées. Votre fenêtre SoapUI se présente comme suit.

Exploration de l’API SOAP Salesforce avec SoapUI

Cliquez sur OK. Après quelques secondes de traitement, un dossier Exploring Salesforce SOAP API s’affiche dans le volet de navigation à gauche de l’écran. Sous ce dossier, une entrée appelée SoapBinding contient plusieurs opérations.

Dossier SoapUI SoapBinding

Que sont ces informations ? Chaque opération correspond à une requête que nous pouvons envoyer à l’API SOAP. Les propriétés de chaque opération sont extraites des informations du fichier WSDL. Chaque opération contient également un exemple de requête XML qui comprend le point de terminaison HTTPS de l’opération et un message SOAP prérenseigné.

Dernière chose : Salesforce exige que toutes les connexions utilisent TLS 1.2 ou supérieur. Si vous utilisez SoapUI avec Java 7, TLS 1.2 n’est pas activé par défaut. Si vous essayez de vous connecter à Salesforce avec une version plus ancienne de TLS, vous recevrez un message d’erreur. La bonne nouvelle, c’est que la solution est très simple. Allez lire cet article de blog bien pratique pour plus d’informations.

Nous sommes maintenant prêts à envoyer des requêtes à l’API SOAP. À l’aventure, compagnon !

Connectez-vous à votre Trailhead Playground.

Dans SoapUI, faites défiler jusqu’à l’opération login. Agrandissez-la, puis double-cliquez sur Request 1. Un exemple de requête de connexion SOAP s’affiche.
Exemple de requête de connexion SOAP
Voici une décomposition rapide de l’URI du point de terminaison (1).
  • https:// : HTTP sécurisé.
  • login.salesforce.com : domaine supérieur d’une requête de connexion.
  • /services/Soap : indique que nous envoyons une requête à l’API SOAP.
  • /C : spécifie que nous utilisons le WSDL enterprise. Pour le WSDL partner, utilisez /u.
  • /36.0 : le numéro de version de l’API. Le préfixe v est manquant, car certaines API l’incluent avant le numéro de version, et d’autres ne l’incluent pas. Ce comportement est une bizarrerie des API Salesforce.
  • /0DF36000000LHZw : numéro de version du package.
Nous n’allons pas utiliser de package géré dans cet exemple. Par conséquent, nous pouvons retirer le numéro de version du package à la fin de l’URI. Retirez-le maintenant.

Le message SOAP (2) contient tout ce qui compose un message SOAP : une enveloppe, un en-tête et un corps.

Les propriétés dans l’élément LoginScopeHeader se rapportent à l’authentification des utilisateurs d’un portail de clients ou en libre-service. Ces valeurs n’étant pas utiles dans notre exemple, supprimez tout l’élément <urn:LoginScopeHeader> (à partir de <urn: LoginScopeHeader> jusqu’à </urn:LoginScopeHeader>). Sélectionnez le texte dans la fenêtre, puis appuyez sur la touche Suppr.

Examinons ensuite l’élément <urn:login> dans le corps du message. Il constitue la majeure partie de la requête de connexion. Nous saisissons nos identifiants utilisateur à cet emplacement. Remplacez les ? par le nom d’utilisateur et le mot de passe que vous utilisez pour votre Trailhead Playground.

Pour ce faire, vous aurez besoin de vos identifiants Trailhead Playground. Depuis le lanceur d’application, cherchez et ouvrez le démarreur de Playground et laissez-vous guider. Si vous ne voyez pas l’application Démarreur de Playground, consultez l’article Recherche du nom d’utilisateur et du mot de passe de votre Trailhead Playground dans l’aide de Trailhead.
  1. Cliquez sur l’onglet Obtenir vos identifiants de connexion et notez votre nom d’utilisateur.
  2. Cliquez sur Réinitialiser mon mot de passe. Cela enverra un e-mail de réinitialisation du mot de passe à l’adresse e-mail associée à votre nom d’utilisateur.
  3. Cliquez sur le lien dans l’e-mail.

Puisque vous effectuez une requête API à partir d’une adresse IP inconnue dans Salesforce, vous devez ajouter votre jeton de sécurité à la fin de votre mot de passe. Par exemple, si votre mot de passe est monmotdepasse et que votre jeton de sécurité et XXXXXXXXXX, saisissez monmotdepasseXXXXXXXXXX dans l’élément <urn:password>.

Pour obtenir votre jeton de sécurité, accédez à vos paramètres personnels, puis accédez à la page Réinitialiser mon jeton de sécurité sous Mes informations personnelles. Cliquez sur Réinitialiser le jeton de sécurité pour envoyer un e-mail contenant votre jeton à l’adresse e-mail associée à votre Trailhead Playground.

Votre message SOAP se présente comme suit.

Un exemple de requête de connexion SoapUI avec les identifiants de notre organisation DE

Cliquez sur le bouton d’activation (triangle vert) en haut à gauche de la fenêtre de la requête. Ce bouton envoie la requête en envoyant votre message SOAP dans une bouteille à la mer. Une fois agrandie, la réponse se présente comme suit.

Réponse de connexion d’API SOAP

Félicitations, capitaine. Vous avez réussi à vous connecter. La réponse contient un certain nombre d’informations sur votre organisation et sur l’utilisateur. Plus important, elle contient l’instance de votre organisation (ou un domaine personnalisé si vous utilisez Mon domaine) et un ID de session que nous allons utiliser pour exécuter de futures requêtes, entourées en rouge ci-dessous.

Serveur de l’instance et ID de session inclus dans la réponse de connexion

Copiez l’instance et l’ID de session dans un fichier texte. Ils vont bientôt nous être utiles.

L’instance de votre organisation est susceptible de changer. Par conséquent, ne codez pas en dur les références à l’instance en élaborant des intégrations ! Utilisez à la place la fonctionnalité Salesforce Mon domaine pour configurer un domaine personnalisé. Un domaine personnalisé non seulement élimine tout problème de changement de nom d’instance, mais met en évidence votre marque, renforce la sécurité de votre organisation et personnalise votre page de connexion.

Mon domaine est déjà activé dans votre Trailhead Playground

N’essayez pas d’activer Mon domaine ou de modifier ses réglages dans votre Trailhead Playground. Par défaut, Mon domaine est déjà activé dans tous les Trailhead Playgrounds.

Nom Mon domaine en surbrillance dans une URL Trailhead Playground.

Dans votre organisation de production, Mon domaine vous permet de créer un sous-domaine unique pour votre organisation. Avec Mon domaine, vous remplacez l’URL d’instance que Salesforce vous attribue, telle que https://na17.lightning.force.com, par un sous-domaine de votre choix, comme https://monnomdedomaine.lightning.force.com.

Mon domaine est requis pour créer des composants Lightning personnalisés et configurer l’authentification unique (SSO) dans une organisation. Pour en savoir plus sur Mon domaine, consultez cet article Knowledge. Pour savoir comment l’activer dans votre organisation de production, consultez le module Authentification des utilisateurs.

Création d'un compte

Comme nous l’avons fait avec l’API REST, nous allons créer un compte avec l’API SOAP. Dans le volet de navigation à gauche de l’écran, accédez à l’opération create. Agrandissez-la, puis double-cliquez sur Request 1.

Comme la création d’un enregistrement est plus complexe que la connexion, le message SOAP create() contient plus d’éléments. La plupart sont inclus dans l’en-tête de la requête et sont facultatifs. Pour simplifier, nous allons supprimer la plupart de ces éléments dans les informations de l’en-tête. Retenez que les options affichées dans ces en-têtes sont disponibles lors de la création d’un enregistrement. Pour en savoir plus sur le rôle de chaque en-tête, consultez la rubrique En-têtes SOAP dans le Guide du développeur d’API SOAP.

Toutefois, nous ne souhaitons pas supprimer l’en-tête SessionHeader. Il va contenir l’ID de session que nous avons reçu dans la réponse login(). Supprimez les autres en-têtes, compris entre <urn:EmailHeader> et </urn:AssignmentRuleHeader>. Votre message se présente comme suit.

Exemple de requête create() dans SoapUI

Copiez l’ID de session que vous avez enregistré dans un fichier texte, puis collez-le dans la balise <urn:sessionId>, en remplaçant le ?.

Nous allons effectuer d’autres ajustements dans le corps de message. Pour commencer, nous allons spécifier que nous créons un compte. Changez le texte de la balise <urn:sObjects> comme suit : <urn:sObjects xsi:type="urn1:Account" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">. Cette ajustement spécifie le type d’enregistrement correct en utilisant la déclaration du schéma d’instance XML.

Nous voulons aussi nommer le compte. Ajoutez <Name>Sample SOAP Account</Name> dans l’élément sObjects. Supprimez également les éléments fieldsToNull et Id. Votre message se présente maintenant comme suit.

Requête Create() avec d’autres éléments supprimés

Un dernier point avant d’exécuter la requête. Changez le point de terminaison pour spécifier l’instance de votre organisation au lieu de login, puis retirez la version du package à la fin de l’URI. L’URI du point de terminaison se présente comme suit: https://na30.salesforce.com/services/Soap/c/36.0.

Nous pouvons envoyer la requête. Cliquez de nouveau sur le triangle vert. Ça marche ! Examinons la réponse.

Réponse SOAP de création d’un compte

Notez l’en-tête LimitInfoHeader. Il renvoie des informations sur votre utilisation d’API. Dans l’exemple ci-dessus, nous avons effectué 9 appels sur 100 000 autorisés aujourd’hui.

Dans le corps de réponse, notez l’élément <result>. <success>true</success> indique que l’enregistrement a été créé avec succès. <id> inclut l’ID de l’enregistrement, que vous pouvez utiliser dans de futures requêtes.

Nous venons de découvrir les concepts de base pour exécuter des requêtes avec l’API SOAP. Bien entendu, chaque opération a ses propres paramètres et particularités. Pour commencer à écrire des intégrations avec l’API SOAP, consultez le Guide du développeur d’API SOAP.

Ressources

SOAP API Developer Guide

SOAP API Cheatsheet

SOAP API Sample WSDL Structures

SOAP API Web Services Connector (WSC)

SoapUI Homepage
Remarque

Remarque

N’oubliez pas que ce module est conçu pour Salesforce Classic. Lorsque vous lancez votre organisation d’exercice, basculez vers Salesforce Classic pour relever ce défi.