Suivez votre progression
Accueil Trailhead
Accueil Trailhead

Utilisation de l’API REST

Objectifs de formation

Une fois cette unité terminée, vous pourrez :
  • Vous connecter au Workbench et accéder à l’explorateur REST
  • Utiliser la ressource describe
  • Créer un compte en utilisant l’API REST
  • Exécuter une requête en utilisant l’API REST

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.

Description de l’objet Account

Il est temps de se mettre à l’eau. Nous allons utiliser le Workbench pour effectuer quelques appels d’API. Workbench est une suite d’outils qui permet d’interagir avec votre organisation Salesforce via l’API. Puisque vous pouvez exécuter des requêtes REST à partir de n’importe quel expéditeur HTTP, vous pouvez utiliser de nombreux autres outils (par exemple cURL ou Postman). Le Workbench fournit toutefois une infrastructure conviviale conçue spécialement pour les API Salesforce. Elle est idéale pour apprendre à écrire une intégration complète.
La première étape consiste à se connecter au Workbench.
  1. Connectez-vous à votre Trailhead Playground et accédez à Workbench.
  2. Pour Environnement, sélectionnez Production.
  3. Pour la version d'API, sélectionnez le nombre le plus élevé.
  4. Assurez-vous de cocher J'accepte les conditions d'utilisation.
  5. Cliquez sur Se connecter avec Salesforce.

Vous êtes sur la page d'accueil de Workbench. Pour ce module, nous allons utiliser un seul outil Workbench, Explorateur REST.

Dans le menu supérieur, sélectionnez utilitaires | Explorateur REST.

REST Explorer du Workbench

Vous pouvez effectuer des appels vers l’API REST depuis l’explorateur REST, comme vous le feriez depuis n’importe quelle autre interface HTTP. Le texte de la zone de texte représente un URI de ressource. Pour simplifier, le domaine supérieur est omis dans l’URI affiché. Par exemple, l’URI complet de la ressource prérenseigné dans la zone de texte URI est https://foo.my.salesforce.com/services/data/v36.0.

Les options au-dessus de cette zone de texte représentent les méthodes HTTP standard. Pour effectuer un appel d’API, saisissez l’URI de la ressource, sélectionnez la méthode appropriée, ajoutez des en-têtes si nécessaire, puis cliquez sur Execute.

Essayons la ressource SObject Describe. Lorsqu’elle est combinée à la méthode GET, cette ressource renvoie les métadonnées d’un objet et de ses champs.

Nous allons essayer de décrire l’objet Account. Remplacez le texte existant dans la zone de texte URI par /services/data/vXX.0/sobjects/account/describe, où XX est mappé avec la version de l’API que vous utilisez.

URI de description d’un compte
Prenons quelques instants pour décomposer l’URI de cette ressource.
  • /services/data : indique que nous envoyons une requête à l’API REST
  • /V36.0 : numéro de version de l’API
  • /sobjects : spécifie que nous accédons à une ressource sous le regroupement sObject
  • /account : il s’agit du sObject actionné (ici, account)
  • /describe : il s’agit de l’action (ici, une requête describe)

Assurez-vous maintenant que la méthode GET est sélectionnée, puis cliquez sur Execute.

Réponse reçue après la description de l’objet Account

Du bon travail capitaine. Les métadonnées Account sont affichées sur l’écran. Le Workbench a mis en forme la réponse pour la rendre plus lisible. Pour afficher la réponse JSON brute, cliquez sur Show Raw Response.

Réponse JSON reçue après la description de l’objet Account

Les métadonnées Account sont affichées en JSON sous quelques en-têtes de réponse HTTP. 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. En regard des méthodes HTTP, cliquez sur Headers. Dans la valeur de l’en-tête Accept, remplacez application/json par application/xml. Vos en-têtes de requête se présentent comme suit.

En-tête de requête spécifiant XML

Cliquez sur Exécuter. 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. Dans la zone de texte de l’URI, remplacez le texte existant par /services/data/vXX.0/sobjects/account, où XX est mappé avec la version de l’API que vous utilisez. Sélectionnez POST. Notez que la zone de texte Request Body s’affiche, dans laquelle nous spécifions les valeurs de champ de notre nouveau compte. Pour commencer, remplaçons l’en-tête Accept par JSON.

Cliquez sur Headers. Remplacez Accept: application/xml par Accept: application/json. Votre requête se présente comme suit.

En-têtes de requête REST
Dans le corps de requête, saisissez le texte ci-dessous.
{
  "Name" : "NewAccount1",
  "ShippingCity" : "San Francisco"
}

Cliquez sur Exécuter. Une réponse semblable à la suivante s’affiche.

Réponse de création de compte réussie dans l’API REST

Si success: true, le compte a été créé avec l’ID renvoyé. Développez le dossier des erreurs pour les consulter.

Par curiosité, créons un deuxième compte sans spécifier le nom du compte. Remplacez le texte du corps de requête par le texte ci-dessous.
{
  "ShippingCity" : "San Francisco"
}

Cliquez sur Exécuter.

Oulala ! Avez-vous reçu une réponse de type REQUIRED_FIELD_MISSING ? Développez le dossier REQUIRED_FIELD_MISSING, puis le dossier fields. Votre réponse développée se présente comme suit.

Si le nom du compte n’est pas saisi, nous obtenons une erreur.
Le champ Name est obligatoire pour la création d’un compte. Par conséquent, le serveur n’a pas traité la requête et nous avons reçu une erreur. Heureusement, toutes les informations nécessaires pour corriger la requête sont indiquées dans la réponse d’erreur. Spécifiez le nom NewAccount2, puis changez la ville d’expédition dans le corps de la requête. Remplacez le texte du corps de requête par le texte ci-dessous.
{
  "Name" : "NewAccount2",
  "ShippingCity" : "New York"
}

Cliquez sur Exécuter. Réussi !

Exécution d’une requête

Imaginons maintenant que vous ou un autre utilisateur créez des centaines de comptes. Vous souhaitez retrouver le nom des comptes dont la ville d’expédition est San Francisco. Vous pouvez utiliser la ressource Query pour exécuter une requête SOQL et retrouver les enregistrements qui vous intéressent – une vraie carte au trésor personnalisée !

Remplacez les données de la zone de texte de l’URI par la ligne suivante : /services/data/v XX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity=’San+Francisco’, où XX est mappé avec la version de l’API que vous utilisez.

Pour coder correctement l’URI dans la chaîne de la requête, nous avons remplacé les espaces par le caractère +. Pour plus d’informations sur le codage d’URL HTML, suivez les liens de la section Ressources. Assurez-vous que la méthode GET est sélectionnée, puis cliquez sur Execute.

Agrandissez le dossier records. Le dossier portant le nom du premier compte que nous avons créé, NewAccount1, est-il affiché ? Très bien ! Cliquez dessus. Cliquez ensuite sur le dossier attributes. L’URI de la ressource du compte renvoyé est affiché en regard de l’URL. Votre réponse se présente comme suit.

La réponse de la requête renvoie un enregistrement de compte

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 le Workbench pour écrire du code, vous interagirez 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 Nforce et Restforce.

Exemple Node.js utilisant Nforce

var nforce = require('nforce');
// create the connection with the Salesforce connected app
var org = nforce.createConnection({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  redirectUri: process.env.CALLBACK_URL,
  mode: 'single'
});
// authenticate and return OAuth token
org.authenticate({
  username: process.env.USERNAME,
  password: process.env.PASSWORD+process.env.SECURITY_TOKEN
}, function(err, resp){
  if (!err) {
    console.log('Successfully logged in! Cached Token: ' + org.oauth.access_token);
    // execute the query
    org.query({ query: 'select id, name from account limit 5' }, function(err, resp){
      if(!err && resp.records) {
        // output the account names
        for (i=0; i<resp.records.length;i++) {
          console.log(resp.records[i].get('name'));
        }
      }
    });
  }
  if (err) console.log(err);
});

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

Ressources

REST API Developer Guide

Getting Started with Salesforce REST in Java

HTML URL Encoding Reference

Workbench
Remarque

Remarque

N’oubliez pas que ce module est conçu pour Salesforce Classic. Lorsque vous lancez votre organisation d’exercice, basculez vers Salesforce Classic pour relever ce défi.