Skip to main content
Build the future with Agentforce at TDX in San Francisco or on Salesforce+ on March 5–6. Register now.

Utilisation de l’API REST

Objectifs de formation

Une fois cette unité terminée, vous pourrez :
  • Vous connecter à l’application Postman et accéder au dossier REST dans la collection d’API Salesforce
  • Utiliser la ressource GET SObject Describe (Décrire)
  • Créer un compte en utilisant l’API REST
  • Exécuter une requête en utilisant l’API REST
Remarque

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.

Ressources et méthodes REST

Terre en vue ! Nous avons repéré l’île REST devant l’étrave, capitaine. Avant d’accoster et de commencer à utiliser l’API, examinons les ressources et les méthodes REST.

Une ressource REST est une abstraction d’une information ou d’une action, par exemple un enregistrement de données unique, un groupe d’enregistrements ou une requête. Dans l’API REST, chaque ressource est identifiée par un URI (Uniform Resource Identifier) nommé, et accédée à l’aide de méthodes HTTP standard (HEAD, GET, POST, PATCH, DELETE). L’API REST est basée sur l’utilisation de ressources, de leurs URI et des liens qui les unissent.

Vous utilisez une ressource pour interagir avec votre organisation Salesforce. Par exemple, vous pouvez :
  • Récupérer une synthèse des informations sur les versions API disponibles pour vous.
  • Obtenir des informations détaillées sur un objet Salesforce, par exemple un Compte, un Utilisateur ou un objet personnalisé.
  • Exécuter une requête ou effectuer une recherche.
  • Mettre à jour ou supprimer des enregistrements.

Une requête REST est formée de quatre composants : un URI de ressource, une méthode HTTP, des en-têtes de requête et un corps de requête. Les en-têtes de requête spécifient les métadonnées de la requête. Le corps de requête spécifie les données de la requête, quand nécessaire. S’il n’existe aucune donnée à spécifier, le corps est omis dans la requête.

Avant d’aller plus loin

Nous allons utiliser Postman pour effectuer quelques appels d’API. Vous pouvez effectuer des requêtes REST à partir de n’importe quel expéditeur HTTP. En outre, Postman n’est qu’un des nombreux outils à votre disposition pour interagir avec votre organisation Salesforce via l’API.  

La première étape consiste à créer un Trailhead Playground, à le connecter à l’application Postman, à configurer le partage des ressources d’origines croisées et à créer une copie de la collection d’API Salesforce. Pour ce faire, vous devez suivre le projet Prise en main rapide : connexion de Postman à Salesforce

Vous pouvez effectuer des appels d’API REST vers votre Trailhead Playground à l’aide des ressources du dossier REST de la collection Salesforce figurant dans l’application Postman, tout comme vous le feriez à partir de n’importe quelle autre interface HTTP. Lorsque vous sélectionnez une ressource dans la collection d’API Salesforce, l’URI est généré en haut de la fenêtre principale. 

Description de l’objet Account

Examinons comment cela fonctionne.

Vous allez utiliser la ressource SObject Describe (Décrire). Lorsqu’elle est combinée à la méthode GET, cette ressource renvoie les métadonnées d’un objet et de ses champs. Décrivons l’objet Account (Compte). 

  1. Dans Collections (Collections), sélectionnez votre copie de Salesforce APIs Collection (Collection d’API Salesforce).
  2. Cliquez sur le dossier REST.
  3. Cliquez sur SObject.
  4. Cliquez sur GET SObject Describe (GET SObject Décrire).
  5. Dans le panneau principal, ouvrez l’onglet Params (Paramètres).
  6. Sous Path Variables (Variables de chemin), dans la ligne SOBJECT_API_NAME, saisissez Account (Compte) au sein de la colonne VALUE (VALEUR).

Fenêtre de requête de Postman affichant l’URI correspondant à SObject Describe (SObject Décrire).


Avant que vous examiniez les résultats de votre requête, prenons quelques instants pour décomposer l’URI de cette ressource.

  • GET : la méthode HTTP utilisée pour cet appel d’API.
  • {{_endpoint}} : l’emplacement où la requête aura lieu. Dans le cas présent, vous avez ajouté l’URL de votre Trailhead Playground au champ _endpoint dans les variables pour vous connecter à Salesforce.
  • /services/data : indique que vous envoyez une requête à l’API REST.
  • /v {{version}} : le numéro de version de l’API. Les guillemets courbes doubles indiquent que ce numéro peut être défini en tant que variable.
  • /sobjects : spécifie que nous accédons à une ressource sous le regroupement sObject.
  • /:SOBJECT_API_Name : le sObject actionné ; dans le cas présent, Account (Compte).
  • /describe : une action ; dans le cas présent, une requête Describe (Décrire).
     7. Cliquez sur Enregistrer.
     8. Cliquez sur Envoyer.

Fenêtre de réponse de Postman affichant les métadonnées de l’objet Account (Compte).

C’est du bon travail, capitaine ! Les métadonnées de Account (Compte) sont affichées sur l’écran et Postman a correctement formaté la réponse. Pour afficher la réponse JSON brute, cliquez sur Raw (Brut).

Les métadonnées de Account (Compte) sont affichées au format JSON. L’API REST prend en charge JSON et XML. Par conséquent, nous allons indiquer, dans l’en-tête de la requête, une réponse XML. 

  1. Dans la fenêtre de requête, cliquez sur Headers (En-têtes).
  2. Ajoutez un nouvel en-tête avec une clé Accept (Accepter) et une valeur application/xml.

Vos en-têtes de requête se présentent comme suit.

Fenêtre de requête de Postman affichant le champ de valeur Headers (En-têtes) défini sur application/xml.

     3. Cliquez sur Envoyer.

La réponse XML brute est renvoyée. Hourra !

Création d'un compte

Créons maintenant un compte en utilisant la ressource SObject la méthode POST. 

Pour créer un compte, procédez comme suit :

  1. Sous REST, sélectionnez SObject, puis sélectionnez POST SObject Create (POST SObject Créer).
  2. Ouvrez l’onglet Params (Paramètres).
  3. Sous Path Variables (Variables de chemin), dans la ligne SOBJECT_API_NAME, saisissez Account (Compte) au sein de la colonne VALUE (VALEUR).
  4. Ouvrez l’onglet Body (Corps).
  5. Remplacez le texte du corps par le code suivant :
{
"Name": "Captain Bly’s Finest Treasure Chests",
"ShippingCity": "Lisbon"
}

Fenêtre de requête de Postman affichant l’URI POST SObject et dans le champ Body (Corps), les détails du compte en cours de création.

6. Cliquez sur Save (Enregistrer).
7. Cliquez sur Envoyer.

Fenêtre de réponse de Postman affichant l’identifiant du compte créé.

Si success: true, le compte a été créé avec l’ID renvoyé. 

Par curiosité, créons un deuxième compte sans spécifier le nom du compte. 

  1. Remplacez le texte du corps de requête par le texte ci-dessous.
{
"ShippingCity" : "Melbourne"
}

Fenêtre de requête de Postman affichant les nouveaux détails d’un nouveau compte.

2. Cliquez sur Envoyer.

Oulala ! Avez-vous reçu la réponse suivante : « Required fields are missing: [Name] » (Des champs obligatoires sont manquants : [Nom]) ? 

Fenêtre de réponse de Postman affichant une erreur indiquant que le champ Name (Nom) n’est pas rempli dans la requête.

Le champ Name (Nom) est obligatoire pour la création d’un compte. Par conséquent, le serveur n’a pas traité la requête et vous avez reçu une erreur. Heureusement, toutes les informations dont vous avez besoin pour corriger la requête sont indiquées dans la réponse d’erreur. Indiquons le nom du compte : « Pirate Pete’s Parrot Pellets » (Granulés pour perroquet de Pete le pirate) dans le corps de la requête. 

  1. Remplacez le texte du corps de requête par le texte ci-dessous.
{
"Name": "Pirate Pete's Parrot Pellets",
"ShippingCity": "Melbourne"
}

     2. Cliquez sur Save (Enregistrer).
3. Cliquez sur Envoyer.

Réussi !

Exécution d’une requête

Imaginons maintenant que vous ou un autre utilisateur créez des centaines de comptes. Vous souhaitez trouver le nom de tous les comptes pour lesquels la ville d’expédition est Melbourne. Vous pouvez utiliser la ressource Query (Requête) pour exécuter une requête SOQL afin de trouver les enregistrements qui vous intéressent, à la manière d’une carte aux trésors personnalisée.

  1. Sous REST, sélectionnez GET Query (GET Requête).
  2. Ouvrez l’onglet Params (Paramètres).
  3. Sous Query Params (Paramètres de la requête), dans la ligne q, à la colonne VALUE (VALEUR), collez le texte suivant.
SELECT Name From Account WHERE ShippingCity = 'Melbourne'

Fenêtre de requête de Postman affichant l’onglet Params (Paramètres) dans lequel la valeur correspondant à q dans la colonne KEY (CLÉ) demande les noms de compte pour lesquels la ville d’expédition est Melbourne.

4. Cliquez sur Save (Enregistrer).
5. Cliquez sur Envoyer.

La requête renvoie le compte que vous venez de créer, Pirate Pete’s Parrot Pellets (Granulés pour perroquet de Pete le pirate). Bon travail, matelot !

Examinez les attributs. L’URI de ressource correspondant au compte renvoyé est affiché en regard de “url”. Votre réponse se présente comme suit.

Fenêtre de réponse de Postman affichant un seul compte renvoyé pour lequel la ville d’expédition est Melbourne. Ce compte est Pirate Pete’s Parrot Pellets (Granulés pour perroquet de Pete le pirate).

Lorsque vous écrivez une intégration, vous pouvez récupérer cet URI dans la réponse pour accéder à plus d’informations sur le compte.

Exemples Node.js et Ruby

Vous connaissez maintenant les possibilités de l’API REST. Bien entendu, lorsque vous quittez Postman pour écrire du code, vous interagissez avec l’API REST en utilisant le langage de programmation de votre choix. Par chance, les développeurs Salesforce experts ont écrit des wrappers pour plusieurs langages qui simplifient le processus de consommation de l’API REST. Voici quelques exemples de requêtes écrites en Node.js et en Ruby qui utilisent respectivement les wrappers JSforce et Restforce.

Exemple Node.js utilisant JSforce

const jsforce = require("jsforce");const conn = new jsforce.Connection({
  // you can change loginUrl to connect to sandbox or prerelease env.
  // loginUrl : "https://test.salesforce.com"
});
// Log in with basic SOAP login (see documentation for other auth options)
conn.login(
  process.env.USERNAME,
  process.env.PASSWORD + process.env.SECURITY_TOKEN,
  (err, res) => {
    if (err) {
      return console.error("Failed to log in to Salesforce: ", err);
    }
    console.log("Successfully logged in!");
    // Run a SOQL query
    conn.query("SELECT Id, Name FROM Account LIMIT 5", (err, result) => {
      if (err) {
        return console.error("Failed to run SOQL query: ", err);
      }
      // Display query results
      const { records } = result;
      console.log(`Fetched ${records.length} records:`);
      records.forEach(record => {
        console.log(`- ${record.Name} (${record.Id})`);
      });
    });
  }
);

Exemple Ruby utilisant Restforce

require 'restforce'
# create the connection with the Salesforce connected app
client = Restforce.new :username => ENV['USERNAME'],
  :password       => ENV['PASSWORD'],
  :security_token => ENV['SECURITY_TOKEN'],
  :client_id      => ENV['CLIENT_ID'],
  :client_secret  => ENV['CLIENT_SECRET']
# execute the query
accounts = client.query("select id, name from account limit 5")
# output the account names
accounts.each do |account|
  p account.Name
end
Partagez vos commentaires sur Trailhead dans l'aide Salesforce.

Nous aimerions connaître votre expérience avec Trailhead. Vous pouvez désormais accéder au nouveau formulaire de commentaires à tout moment depuis le site d'aide Salesforce.

En savoir plus Continuer à partager vos commentaires