Utilisation de l’API SOAP

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.

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.

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.

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

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 !

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.

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.

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.

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.

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 le nom Mon domaine de votre organisation et un ID de session que nous allons utiliser pour exécuter de futures requêtes, entourées en rouge ci-dessous.

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 plutôt l’URL de connexion Mon domaine de votre organisation. Avec Mon domaine, vous pouvez configurer un domaine propre au client pour votre organisation Salesforce. Mon Domaine non seulement élimine tout problème de changement de nom d’instance, mais met aussi en évidence votre marque, renforce la sécurité de votre organisation et personnalise votre page de connexion.