Utilisation de l’API de transfert en masse 2.0

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

• Décrire la différence entre une requête asynchrone et une requête synchrone
  
• Créer une tâche en masse à l’aide de l’application Web Postman
  
• Importez des données dans votre organisation Salesforce en ajoutant des données à une tâche.
  
• Surveiller la progression d'une tâche
  
• Récupérez les résultats d’une tâche.
  

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.

API de transfert en masse et requêtes asynchrones

L’API de transfert en masse repose sur les principes de REST. Elle est optimisée pour les volumes de données importants. Vous pouvez l’utiliser pour insérer, mettre à jour, mettre à jour/insérer ou supprimer un grand nombre d’enregistrements de façon asynchrone, ce qui signifie que vous pouvez soumettre une requête et récupérer les résultats plus tard. Salesforce traite la requête en arrière-plan.

Par contre, les API REST et SOAP utilisent des requêtes synchrones et sont optimisées pour les applications clientes en temps réel qui mettent à jour quelques enregistrements à la fois. Vous pouvez utiliser ces API pour traiter de nombreux enregistrements, mais ils sont moins pratiques pour traiter des jeux de données contenant des centaines de milliers d'enregistrements. L’infrastructure asynchrone de l’API de transfert en masse est conçue pour simplifier et optimiser le traitement de données contenant des milliers ou des millions d’enregistrements.

Pour utiliser l’API de transfert en masse, le plus simple est de l’activer pour traiter les enregistrements dans Data Loader à l’aide de fichiers CSV. Data Loader vous évite d’écrire votre propre application cliente. Il se peut parfois que des exigences uniques nécessitent l’écriture d’une application personnalisée. L’API de transfert en masse vous permet de prendre le contrôle du bateau et de mettre le cap vers une solution adaptée à vos besoins.

Dans cette unité nous utilisons une nouvelle version de l’API de transfert en masse, appelée Bulk API 2.0. Si vous voulez mettre en application ce que vous avez appris dans cette unité à la version précédente de l’API de transfert en masse, toujours prise en charge, vous devez utiliser des URI de ressource différentes, et créer et gérer des lots en plus des tâches. Pour plus d’informations sur la version précédente de l’API de transfert en masse, consultez le guide du développeur d’API de transfert en masse.

Configuration de votre Playground et de Postman

Pour explorer l’API de transfert en masse, vous allez utiliser Postman afin de créer quelques enregistrements de compte.

1. Connectez-vous à votre Trailhead Playground.
   
2. Connectez-vous à l’application Web Postman.
   
3. Connectez votre Playground à Postman en obtenant un nouveau jeton.
   
4. Vérifiez que votre connexion fonctionne avec la ressource REST GET Limits.
   

Vous avez appris à le faire lors du projet Prise en main rapide : connexion de Postman à Salesforce. Si vous avez des doutes au sujet de l’une des étapes, consultez à nouveau ce projet.

Création d’une tâche en masse

La première étape consiste à créer une tâche dans votre copie de la collection d’API Salesforce. Une tâche spécifie le type d’opération et l’objet de données avec lequel vous travaillez. Cela fonctionne comme un compartiment dans lequel vous ajoutez les données à traiter.

1. Dans Collections (Collections), ouvrez le dossier Bulk v2.
   
2. Cliquez sur POST Create Job (POST Créer une tâche).
   

Comme l’API de transfert en masse est basée sur REST, cette requête se présente sous la forme habituelle d’une requête REST composée de quatre éléments : URI, méthode HTTP, en-têtes et corps. La méthode HTTP est POST.

Vous remarquerez que lorsque vous avez cliqué sur la ressource dans la collection, l’URI suivant est apparu dans la fenêtre principale : /services/data/v{{version}}/jobs/ingest. Notez les points suivants sur cet URI.

• Nous utilisons /services/data, qui est le même point de terminaison employé pour l’API REST. L’API par lot utilise le même framework que l’API REST, ce qui signifie que l’API par lot prend en charge beaucoup de ses fonctionnalités, comme l’authentification OAuth.
  
• /jobs/ingest indique que vous accédez à la ressource pour créer des tâches d’API par lot.
  

Créons le corps de la requête.

Afin de créer une tâche d’API de transfert en masse 2.0, utilisez le champ de requête lineEnding pour indiquer la fin de ligne utilisée pour créer le texte au format CSV. L’API de transfert en masse 2.0 prend en charge deux formats de fin de ligne : le saut de ligne (LF) et le retour chariot +saut de ligne (CRLF). La valeur lineEnding par défaut, si elle n’est pas précisée, est LF. Différents systèmes d’exploitation utilisent différents caractères pour marquer la fin d’une ligne :

• Unix / Linux / OS X utilisent LF (saut de ligne, '\n' 0x0A)
  
• Windows / DOS utilisent CRLF (retour chariot suivi d’un saut de ligne, '\r\n', 0x0D0A)
  

Les éditeurs de texte utilisés pour créer un fichier CSV peuvent être configurés pour un format de fin de ligne spécifique qui remplace le format par défaut du système d’exploitation.

1. Copiez et collez l’exemple du corps CSV de votre navigateur dans un éditeur de texte pour effacer le formatage. Indiquez la fin de ligne appropriée avec le champ de demande lineEnding selon le système d’exploitation et l’éditeur de texte que vous utilisez. Dans l’exemple, nous utilisons un ordinateur Windows avec la valeur « CRLF » pour le paramètre lineEnding.
   

{
"operation" : "insert",
"object" : "Account",
"contentType" : "CSV",
"lineEnding" : "CRLF"
}

     2. Cliquez sur Save (Enregistrer).

3. Cliquez sur Send (Envoyer) et examinez la réponse.

La réponse inclut toutes sortes de propriétés relatives à la tâche, la plupart inutiles dans notre exemple, car vous n’avez pas encore ajouté de données. Nous allons toutefois examiner quelques éléments. 

1. Observez la ligne "id". Elle affiche l’ID de tâche renvoyé correspondant à cette tâche.
   

1. À présent, dans la section Request (Requêtes), cliquez sur l’onglet Tests (Tests).
   
2. Ce script ajoute automatiquement l’ID de tâche à la variable __jobID. Cela a pour effet d’injecter l’ID de tâche dans les requêtes futures, afin que vous n’ayez pas besoin de le copier et de le coller.
   

2. Observez ensuite la propriété "state".
   

1. Lorsque vous créez une tâche, elle est immédiatement définie sur l’état Open. Cela signifie qu’elle est prête à recevoir des données.
   

3. Enfin, observez la propriété "contentUrl".
   

1. Cette propriété affiche l’URL que vous utilisez pour charger les données de la tâche.
   

Ajout de données à la tâche

Vous pouvez maintenant insérer des données de compte dans notre tâche. Les données d'une tâche sont envoyées au serveur sous la forme d'un jeu d’enregistrements dans une requête PUT. Le serveur traite le jeu d’enregistrements et détermine la façon optimale de charger les données dans Salesforce. Vous n’avez qu’à charger les données.

Créez une requête dans Postman. Dans votre copie de la collection d’API Salesforce, dans le dossier Bulk v2, cliquez sur PUT Upload Job Data (PUT Charger les données de tâche). Vous remarquerez que la méthode HTTP est PUT.

Dans notre exemple, vous ajoutez un ensemble d’enregistrements ne comprenant que quatre comptes. Généralement, vous utilisez l’API de transfert en masse pour ajouter des milliers voire des millions d’enregistrements, mais le principe reste le même. Vous pouvez charger un fichier CSV en sélectionnant la case d’option et en chargeant votre fichier .csv, ou vous pouvez coller une liste. Dans cet exemple, nous allons coller une liste.

1. Cliquez sur l’onglet Body (Corps) et sélectionnez Raw (Brut) dans la liste déroulante.
   
2. Copiez le texte suivant dans un éditeur de texte pour effacer tout formatage superflu, puis copiez-le à partir du fichier texte vers le champ du corps de la requête.
   

"Name"
"Global Treasures & Mapping Company"
"Ahab’s Mighty Masts"
"Planks R Us"
"Cap’n Cook’s Kitchen Supplies"

3. Cliquez sur Headers. Vous remarquerez que le type de contenu est text/csv. Cela s’explique par le fait que vous avez spécifié le type de contenu dans votre première requête.

     4. Cliquez sur Save (Enregistrer).

5. Cliquez sur Envoyer.

La réponse contient uniquement le code de statut 201 Created (201 Créé), qui indique que Salesforce a bien reçu les données de tâche.

Fermeture de la tâche

Maintenant que vous avez soumis vos données, vous devez informer Salesforce qu’il est temps de les traiter. 

1. Dans le dossier de requête Bulk v2 de votre copie de l’API Salesforce, cliquez sur PATCH Close or Abort a Job (PATCH Fermer ou abandonner une tâche).
   
2. Cliquez sur l’onglet Body (Corps) et notez que "state": est déjà renseigné avec « UploadComplete ».
   

     3. Cliquez sur l’onglet Headers (En-têtes). Vous remarquerez que Content-Type (Type de contenu) est défini sur application/json.

4. Cliquez sur Envoyer.

La réponse contient les informations de statut de la tâche. La propriété state indique que l’état de la tâche est UploadComplete (Chargement terminé). À ce stade, Salesforce arrête de traiter la tâche.

Vérification du statut de la tâche

Vous avez soumis vos données et vous avez informé Salesforce que vous avez terminé d’en charger. Le serveur va maintenant traiter la requête. Vous pouvez suivre la progression du traitement par le serveur en consultant le statut de la tâche par le biais de l’interface utilisateur de Salesforce ou via l’API. Intéressons-nous de plus près à chacune de ces méthodes.

Voici comment vérifier le statut de la tâche dans votre Trailhead Playground. 

1. Dans Setup (Configuration), saisissez Bulk Data Load Jobs (Tâches de chargement de données en masse) dans la zone Quick Find (Recherche rapide).
   
2. Sélectionnez Tâches de chargement de données en masse.
   

Vous pouvez consulter le statut d’une tâche sur cette page. Alternativement, vous pouvez cliquer sur l’ID d’une tâche pour consulter son statut et obtenir des résultats détaillés à son sujet.

Voici comment vérifier le statut de la tâche dans Postman à partir du dossier Bulk v2.

1. Sélectionnez GET Job Info (GET Informations sur la tâche). Vous remarquerez que la méthode HTTP utilisée pour ce type de requête est GET.
   
2. Cliquez sur Envoyer.
   

Une page semblable à la suivante s’affiche.

Si vous constatez que l’état est toujours défini sur UploadComplete (Chargement terminé) au lieu de JobComplete (Tâche terminée), cela signifie que Salesforce est encore en train de traiter la tâche. Ne vous inquiétez pas, il sera traité dans quelques minutes. Allez prendre un chocolat chaud en attendant et réessayez la même requête lorsque vous revenez. Si par chance votre tâche est déjà traitée, continuez pour récupérer les résultats.

Récupération des résultats de la tâche

Une fois qu’une tâche est dans l’état JobComplete (Tâche terminée) (ou Failed [Échouée]), vous pouvez obtenir des informations sur les résultats, sous la forme d’une indication de quels enregistrements ont été traités avec succès ou non.

Examinons quels enregistrements ont été traités avec succès dans le dossier Bulk v2.

1. Cliquez sur la ressource GET Get Job Successful Record Results (GET Obtenir les résultats d’enregistrements réussis de la tâche). Vous remarquerez que la méthode HTTP est GET.
   
2. Cliquez sur Envoyer. Une page semblable à la suivante s’affiche.
   

Salesforce renvoie une liste de tous les enregistrements de la tâche qui ont été traités avec succès. Dans ce module, vous avez créé plusieurs enregistrements de compte. La ligne 1 affiche les types de valeurs des réponses renvoyées en dessous. Les données de la liste contiennent les ID d’enregistrement des enregistrements créés, une valeur true (vrai) pour les colonnes sf__Created et les noms des comptes créés. Bon travail ! 

Il arrive parfois que certains enregistrements ne puissent être traités. La tâche peut, par exemple, avoir essayé de créer des enregistrements de compte qui existaient déjà. Ou alors il manquait des champs obligatoires dans les données de la tâche. Dans ces scénarios, vous pouvez demander à Salesforce de fournir une liste des enregistrements ayant présenté une erreur durant le traitement, accompagnée d’informations complémentaires sur les problèmes survenus. Examinons les enregistrements dont le traitement a échoué dans le dossier Bulk v2.

1. Sélectionnez la ressource GET Get Job Failed Record Results (GET Obtenir les résultats d’enregistrements échoués de la tâche). Vous remarquerez que la méthode HTTP est encore une fois GET.
   
2. Cliquez sur Envoyer. Le résultat se présente comme suit.
   

Postman fournit une liste des enregistrements ayant rencontré des erreurs durant le traitement, avec pour chacun d’entre eux l’ID d’enregistrement et le message d’erreur pertinent. Dans notre cas, tous le enregistrements ont bien été insérés, donc cette liste d’enregistrements est vide. Voilà du travail bien fait, capitaine !

Ressources

• Guides pour développeurs : Bulk API 2.0 Developer Guide
  
• Guides pour développeurs : Bulk API Developer Guide (version antérieure de l’API de transfert en masse, non abordée dans cette unité)