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
  

Remarque

Vous souhaitez apprendre en français ? Commencez le défi dans un Trailhead Playground en français et utilisez les traductions fournies entre crochets pour naviguer. Copiez et collez uniquement les valeurs en anglais, car les validations de défi reposent sur les données en anglais. Si vous ne réussissez pas le défi dans votre organisation en français, nous vous recommandons (1) de définir le paramètre régional sur les États-Unis, (2) de définir la langue sur l’anglais en suivant les instructions ici, puis (3) de cliquer à nouveau sur le bouton « Vérifier le défi ».

Consultez le badge Trailhead dans votre langue pour découvrir comment profiter de l’expérience Trailhead traduite.

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 Setup (Configuration), saisissez « API » dans la zone Quick Find (Recherche rapide), puis sélectionnez API. Dans la page API WSDL, cliquez sur Générer WSDL Enterprise.

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 au format XML 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.

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 la version de Java utilisée par SoapUI en sélectionnant Help (Aide) | System Settings (Paramètres système) depuis SoapUI. Pour plus d’informations, reportez-vous à www.soapui.org.

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é Exploring Salesforce SOAP API (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 !

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.

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 l’application Playground Starter et laissez-vous guider. Si vous ne voyez pas l’application Playground Starter, consultez l’article Recherche du nom d’utilisateur et du mot de passe de votre Trailhead Playground dans l’aide Salesforce.

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>.

Cliquez sur votre avatar en haut à droite de l’écran, sélectionnez Settings (Paramètres), puis choisissez Reset My Security Token (Réinitialiser mon jeton de sécurité) sous My Personal Information (Mes informations personnelles). Cliquez sur Reset Security Token (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.

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.

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.

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 ressemble à ceci : https://NomMonDomaine.trailblaze.develop.my.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.

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