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

Vous souhaitez apprendre en français ? Dans ce badge, les validations de défi pratique Trailhead se font en anglais. Les traductions sont fournies entre parenthèses à titre de référence. Dans votre Trailhead Playground, veillez (1) à définir les États-Unis comme région, (2) à sélectionner l’anglais comme langue, et (3) à copier et coller uniquement les valeurs en anglais. Suivez les instructions ici.

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

Ressources et méthodes REST

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

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

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.

{
"Name": "Captain Bly’s Finest Treasure Chests",
"ShippingCity": "Lisbon"
}

{
"ShippingCity" : "Melbourne"
}

SELECT Name From Account WHERE ShippingCity = 'Melbourne'

Exemples Node.js et Ruby

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})`);
      });
    });
  }
);

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

Ressources