Utilisation de l’API de transfert en masse 2.0

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 requête lineEnding selon le système d’exploitation et de 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"
}

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.

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 » (Chargement terminé).

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

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 Configuration, saisissez Tâche de chargement de données en masse dans la zone 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 : 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é)