Utilisation de l'API de transfert en masse

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 par lot en utilisant l’explorateur REST dans le Workbench
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.

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.

Importation des données de votre organisation

Pour explorer l’API de transfert en masse, nous allons utiliser le Workbench afin de créer quelques enregistrements de compte.

Création d’une tâche en masse

L’API de transfert en masse est basée sur REST. Par conséquent, nous pouvons utiliser l’explorateur REST du Workbench pour exécuter les requêtes de l’API de transfert en masse.

Connectez-vous à votre Trailhead Playground et accédez à Workbench.
Pour Environnement, sélectionnez Production. Pour la version d'API, sélectionnez le nombre le plus élevé. Assurez-vous de cocher J'accepte les conditions d'utilisation.
Cliquez sur Se connecter avec Salesforce.
Dans le menu supérieur, sélectionnez utilitaires | Explorateur REST.

Nous sommes prêts à charger nos données. La première étape consiste à créer une tâche. Une tâche spécifie le type d’opération et l’objet de données avec lequel nous travaillons. Cela fonctionne comme un compartiment dans lequel nous ajoutons les données à traiter.

Nous allons utiliser la ressource /jobs/ingest pour créer une tâche. Cette ressource permet également d'obtenir une liste des tâches en cours.

Pour créer une tâche, nous soumettons une requête POST à la ressource /jobs/ingest avec les propriétés de la tâche dans le corps de la requête. 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. Comme nous venons de l’indiquer, la méthode est POST.

Remplacez la valeur de la zone de texte de l’URI par la ligne suivante : /services/data/v XX.0/jobs/ingest, où XX.0 correspond à la version de l’API que vous utilisez. Notez les points suivants sur cet URI.

Nous utilisons /services/data, qui est le même point de terminaison que 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 nous accédons à la ressource pour créer des tâches via l’API de transfert en masse.

Pour le corps de la requête, copiez et collez le texte suivant.

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

Ces propriétés indiquent que nous souhaitons utiliser l’opération insert dans les données que nous soumettons à la tâche. Nous soumettons des données de compte, sous le format CSV. L’API de transfert en masse accepte des charges de travail CSV.

Votre explorateur REST se présente comme suit.

Cliquez sur Execute et examinez la réponse.

La réponse inclut toutes sortes de propriétés sur la tâche, la plupart inutiles dans notre exemple, car nous n’avons pas encore ajouté de données. Nous souhaitons toutefois mettre le doigt sur deux propriétés. Recherchez l’ID de la tâche (id) et copiez-le dans un fichier texte. Nous l’utilisons pour ajouter des données à la tâche et vérifier son statut. Examinez également la propriété state. 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. Regardons enfin la propriété contentUrl. Cette propriété montre l’URL que nous utilisons pour charger les données de la tâches.

Ajout de données à la tâche

Nous pouvons 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 nouvelle requête dans Workbench. Remplacez les données de la zone de texte de l’URI par la ligne suivante : /services/data/v XX.0/jobs/ingest/jobID/batches. Remplacez jobID par l’ID de la tâche que vous avez copié. Pour la méthode HTTP, sélectionnez PUT.

Dans notre exemple, nous ajoutons un jeu d’enregistrements comprenant seulement 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. Copiez le texte CSV suivant dans le corps de requête.

"Name"
"Sample Bulk API Account 1"
"Sample Bulk API Account 2"
"Sample Bulk API Account 3"
"Sample Bulk API Account 4"

Nous utilisons des données CSV car nous l’avons spécifié en créant la tâche.

Cliquez sur Headers et passez Content-Type sur Text/csv. Votre requête se présente comme suit.

Ajoutez les données de tâche à l’aide de l’explorateur REST

Cliquez sur Exécuter.

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

Fermeture de la tâche

Maintenant que nous avons soumis nos données, il faut informer Salesforce qu’il est temps de les traiter. Pour cela, faites passer la tâche de l’état Open à UploadComplete.

Remplacez les données de la zone de texte de l’URI par la ligne suivante : /services/data/v XX.0/jobs/ingest/jobID. Là encore, remplacez XX par la version de l’API que vous utilisez et remplacez jobID par l’ID de la tâche. Pour la méthode HTTP, sélectionnez PATCH. Cliquez sur Headers et passez Content-Type sur application/json. Remplacez le texte du corps de la requête par le texte JSON ci-dessous.

{
   "state" : "UploadComplete"
}

Cliquez sur Exécuter. 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. À ce stade, Salesforce arrête de traiter la tâche.

Vérification du statut de la tâche

Nous avons soumis nos données. Nous avons informé Salesforce que nous avons terminé de charger nos données. Le serveur va maintenant traiter la requête. Nous pouvons suivre la progression du traitement par le serveur en consultant le statut de la tâche via l’API ou l’interface utilisateur de Salesforce. Dans Salesforce, accédez à Configuration et saisissez « Tâches de chargement de données en masse » dans la case Recherche rapide, puis 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.

Dans l’API, c’est la ressource /jobs/ingest/jobID qui permet de surveiller une tâche. Remplacez les données de la zone de texte de l’URI par la ligne suivante : /services/data/v XX.0/jobs/ingest/jobID, avec les remplacements habituels. Pour la méthode HTTP, sélectionnez GET.

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

Si state est toujours UploadComplete au lieu de JobComplete, Salesforce est encore en train de traiter la tâche. Ne vous inquiétez pas, il sera traité dans quelques minutes. Allez prendre un verre 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, ce qui ne vous empêche pas de prendre une pause café.

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

Une fois qu’une tâche est dans l’état JobComplete (ou Failed), nous pouvons obtenir des informations sur les résultats, sous la forme d’enregistrements traités avec succès ou non.

Examinons d'abord les enregistrements qui ont bien été traités. Dans l’explorateur REST du Workbench, remplacez la valeur de la zone de texte de l’URI par la ligne suivante : /services/data/v XX.0/jobs/ingest/jobID/successfulResults, avec les remplacements habituels. Pour la méthode HTTP, sélectionnez GET.

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

Salesforce renvoie du CSV contenant une liste de tous les enregistrements de la tâche qui ont bien été traités. Dans ce module, nous avons créé plusieurs enregistrements de compte. Les données CSV contiennent l’ID de l’enregistrement créé, ainsi que la valeur « true » pour la colonne sf_Created.

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, nous pouvons demander à Salesforce une liste des enregistrements ayant présenté une erreur durant le traitement, ainsi que des informations complémentaires sur le problème survenu.

Dans l’explorateur REST, remplacez la valeur de la zone de texte de l’URI par la ligne suivante : /services/data/v XX.0/jobs/ingest/jobID/failedResults, avec les remplacements habituels. Pour la méthode HTTP, sélectionnez GET.

Cliquez sur Exécuter. Le résultat se présente comme suit.

Salesforce fournit des données CSV contenant une liste des enregistrements ayant rencontré des erreurs durant le traitement, ainsi que l’ID d'enregistrement et le message d'erreur. Dans notre cas, tous le enregistrements ont bien été insérés, donc cette liste d’enregistrements est vide. Du travail propre capitaine !

Ressources

Bulk API 2.0 Developer Guide

Guide du développeur d’API de transfert en masse (version antérieure de l’API de transfert en masse, non abordée dans cette unité)

Workbench

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.

Thèmes