Partie I : Création de points de terminaison d’API personnalisés

Première partie : API basées sur SOAP

Simple Object Access Protocol (SOAP) est un protocole de messagerie basé sur des requêtes et des réponses utilisant un format XML. Bien que certains systèmes hérités utilisent encore SOAP sur SMTP, la méthode de transport généralement utilisée pour les requêtes SOAP est HTTP. En tant que protocole API, SOAP est indépendant de la plate-forme et du langage, permettant à deux applications s’exécutant sur des systèmes complètement différents de communiquer entre elles.

Cet article fait partie d’une série en deux parties expliquant comment créer des points de terminaison d’API personnalisés dans Salesforce avec APEX. Dans la première partie, nous expliquerons comment créer un point de terminaison d’API basé sur SOAP que d’autres applications utiliseront lors de la communication avec votre organisation Salesforce.

Une brève introduction à SOAP

Chaque message SOAP est contenu dans un envelope, qui a un en-tête et un corps. L’en-tête contient des informations relatives à l’application, telles que la date à laquelle le message a été généré ou les identifiants liés au contexte du message. Le corps contient le message réel. Voici un exemple de message SOAP avec un format qui serait utilisé pour l’authentification auprès de Salesforce :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:enterprise.soap.sforce.com">
   <soapenv:Header>
      <urn:LoginScopeHeader>
         <urn:organizationId>12345</urn:organizationId>
         <urn:portalId>abcde</urn:portalId>
      </urn:LoginScopeHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:login>
         <urn:username>johndoe</urn:username>
         <urn:password>mypassword</urn:password>
      </urn:login>
   </soapenv:Body>
</soapenv:Envelope>

Étant donné que chaque message a la même structure, SOAP est indépendant du système. Par exemple, une application s’exécutant sur une machine Windows 11 peut envoyer un message à une autre application s’exécutant sur un serveur Web basé sur Unix.

Bien que le message puisse être envoyé via SMTP ou HTTP, les messages SOAP doivent idéalement être envoyés via HTTPS, avec une authentification simple ou mutuelle.

SOAP est principalement utilisé pour créer un API ou alors service Web pour échanger des informations de serveur à serveur. Par conséquent, il est très important que les deux systèmes établissent la confiance. Salesforce fournit plusieurs façons d’effectuer l’authentification.

La relation entre le savon et WSDL

Bien que tous les messages SOAP aient la même structure, la spécification SOAP ne définit pas d’autres aspects, tels que le format de message ou le protocole de transport. Le langage de description des services Web (WSDL) décrit les formats de message, les détails de transport et les opérations du service Web. Le fichier WSDL peut être considéré comme un contrat entre le client et le service.

Comment créer une API basée sur Soap dans Salesforce

Maintenant que nous avons couvert les principes fondamentaux, commençons à implémenter notre API SOAP.

Configurer une organisation Salesforce

Tout d’abord, vous avez besoin d’une organisation Salesforce. Salesforce fournit des organisations gratuites Developer Edition, et l’inscription à l’une d’entre elles est simple. Rendez-vous sur la page d’inscription et indiquez vos coordonnées. Vous devriez recevoir un lien d’invitation dans quelques minutes.

Création d’une classe globale avec Apex

Pour créer un service Web SOAP dans Salesforce, nous devrons créer une classe personnalisée Apex définie globalement. Dans notre classe, nous utiliserons le webservice mot clé et static modificateur de définition pour chaque méthode que nous voulons exposer. Ajout de la webservice Le mot-clé donne automatiquement un accès global à la méthode à laquelle il est ajouté.

Afin de créer cette classe dans notre nouvelle organisation brillante, nous allons à Installer puis trouver Code personnalisé -> Classes Apex. Dans le tableau listant les classes existantes, on clique sur Nouveau.

Pour en savoir plus sur Apex et sur la création de classes, consultez cette page Trailhead et la documentation Apex.

Ci-dessous, nous avons un échantillon ContactAPI classe qui expose une createContact méthode utilisée pour créer de nouveaux enregistrements de contact dans Salesforce. La méthode accepte les détails d’un contact comme paramètres et insère un nouvel enregistrement de contact.

En cas de succès, il renvoie l’ID du nouveau Contact accompagné d’un message. En cas d’échec, il renvoie un message d’erreur. Veuillez copier le code et le coller dans la classe vide nouvellement créée.

global class ContactAPI {
  webservice static String createContact (String firstName, String lastName, String contactEmail, String salutation) { 
    try {
      Contact newContact = new Contact();
      newContact.Salutation = salutation;
      newContact.FirstName = firstName;
      newContact.LastName = lastName;
      newContact.Email = contactEmail;

      insert newContact;
      return 'Successfully inserted new Contact! Id:' + String.valueOf(newContact.Id);
    } catch (Exception e) {
      return 'Error:' + e.getMessage();
    }
  }
}

Ensuite, nous cliquons Sauver.

C’est ça! Notre service Web est prêt à fonctionner. Nous avons créé avec succès une API SOAP dans Salesforce.

Générer le WSDL

Nous devons maintenant générer un fichier WSDL et le fournir à l’application externe ou aux développeurs tiers qui peuvent ensuite le consommer pour appeler notre createContact méthode.

Salesforce fournit deux fichiers WSDL prêts à l’emploi pour intégrer les applications clientes à Salesforce :

Les WSDL d’entreprise est optimisé pour une seule organisation Salesforce. Il est fortement typé, ce qui signifie qu’il contient des objets et des définitions de champ pour cette organisation particulière. Chaque fois qu’il y a un changement dans les métadonnées (objet et/ou champs) dans l’organisation Salesforce, un nouveau WSDL doit être généré et fourni au client (pour le consommer à nouveau).
Les Partenaire WSDL est optimisé pour une utilisation avec de nombreuses organisations Salesforce. Il est vaguement typé et ne change pas en fonction de la configuration spécifique d’une organisation.

Afin d’utiliser notre service Web, nous utiliserons le WSDL pour notre classe Apex (pour appeler notre service Web) et nous utiliserons le WSDL d’entreprise pour nous authentifier auprès de Salesforce.

Après avoir créé notre ContactAPI classe, nous la voyons apparaître dans la liste des classes Apex. Dans la rangée pour ContactAPI, nous cliquons sur le WSDLName lien pour générer un WSDL.

Cela ouvrira un nouvel onglet avec notre WSDL, qui ressemblera à ceci :

Nous enregistrons ce fichier sur notre machine locale, en le nommant contactAPI-wsdl.xml.

Pour générer le WSDL d’entreprise pour notre organisation Salesforce, nous allons à la page de configuration, puis trouvons Intégrations -> API. Ensuite, on clique sur Générer le WSDL d’entreprise.

Votre WSDL généré devrait ressembler à ceci :

Nous enregistrons ce fichier sur notre machine locale, en le nommant enterprise_wsdl.xml.

Pour générer le WSDL pour votre classe Apex :

Accédez à la page Configuration.
Tapez et sélectionnez Classes Apex.
Trouvez votre classe. Dans notre cas, c’est ContactAPI. Cliquez sur le nom.
Sur l’écran suivant, vous aurez la page de classe où vous avez le Générer WSDL bouton.

Tester et valider

Pour nous assurer que le service Web fonctionne, nous allons le consommer en l’appelant depuis notre application Web et voir s’il répond correctement. Nous verrons également comment valider notre API avec des tests unitaires.

Consommer l’API

Pour les besoins de cette démo, nous utiliserons SoapUI, qui est un outil open source pour tester les services Web SOAP (et d’autres protocoles). Avec SoapUI installé et en cours d’exécution, nous créons un nouveau projet SOAP, en fournissant un nom et en sélectionnant notre enterprise_wsdl.xml fichier en tant que WSDL initial.

Nous avons maintenant tous les SoapBindings Salesforce disponibles répertoriés sur la gauche.

Tout d’abord, nous devons authentifier notre application Web auprès de Salesforce. Nous le faisons en utilisant le login appeler et fournir nos identifiants de connexion.

Utiliser un jeton de sécurité

Pour plus de sécurité, nous devons également ajouter un Jeton de sécurité à notre mot de passe pour s’authentifier. Nous pouvons obtenir un jeton de sécurité en allant sur le Paramètres page et en sélectionnant Réinitialiser mon jeton de sécurité à gauche. Ensuite, appuyez sur le bouton du même nom. Nous recevrons ensuite notre jeton de sécurité par e-mail.

Connectez-vous avec le jeton et les informations d’identification

Avec notre jeton en main, nous sélectionnons le login SoapBinding dans SoapUI. Assurez-vous d’avoir l’URL correcte en fonction de votre organisation. Si vous venez de créer un compte de développeur, l’URL doit être : https://login.salesforce.com. Si vous testez cela dans une Sandbox, l’URL doit être : https://test.salesforce.com. Idéalement, l’Enterprise WSDL généré aura déjà l’URL correcte.

Pour les tests de démonstration, nous pouvons commenter tous les autres paramètres à l’exception du nom d’utilisateur et du mot de passe.

Nous appuyons sur le vert Jouer bouton en haut à gauche de la fenêtre pour envoyer la requête. Nous recevons une réponse qui ressemble à ceci :

Les éléments critiques que nous recherchons dans la réponse sont sessionId et serverUrl. Pour appeler notre service Web, nous devons fournir le sessionId avec d’autres paramètres dans notre appel. Nous copions ceci sessionIdcar nous en aurons besoin plus tard.

Appelez notre API Soap

Appelons notre ContactAPI classe et créez un contact dans Salesforce. Pour ce faire, nous devons ajouter notre fichier ContactAPI WSDL, contactAPI-wsdl.xml, à notre projet. Nous faisons un clic droit sur le dossier du projet et sélectionnons Ajouter WSDL.

Après avoir ajouté le WSDL, il apparaît également dans le menu de gauche, comme ci-dessous. Double-cliquez sur Demande 1 pour voir la demande. Pour cet exemple, nous pouvons tout supprimer de l’en-tête de l’enveloppe SOAP à l’exception de SessionHeader avec sessionId nœud.

Après avoir supprimé les nœuds indésirables, nous fournissons le sessionId que nous avons copié à partir de notre appel de connexion plus tôt. Puis, dans le Body section de l’enveloppe, nous fournissons les coordonnées du contact à créer.

Nous appuyons sur le vert Jouer bouton en haut à gauche. Voila ! Nous avons créé avec succès un contact dans Salesforce et reçu son Id.

Vérifier l’organisation Salesforce pour un nouveau contact

Regardons à l’intérieur de notre organisation Salesforce pour voir si tout a été créé correctement. Nous allons dans notre organisation Salesforce, cliquez sur le Lanceur d’application icône de gaufre sur la gauche, puis tapez Contact dans la barre de recherche pour trouver et sélectionner Contacts.

Par défaut, nous atterrissons sur la page Contacts avec le Contacts récemment consultés vue liste. Cliquez sur la flèche vers le bas et sélectionnez soit Tous les contacts ou alors Mes contacts vue liste.

Note: Si vous êtes dans une organisation de développeur, vous verrez un ensemble de contacts factices (et d’autres enregistrements) créés par Salesforce pour vous permettre de tester la plateforme.

Nous tapons le nom de notre contact nouvellement créé dans la zone de recherche de liste à droite, et nous voyons notre nouveau contact !

Lorsque nous cliquons sur le nom du contact, nous nous retrouvons…