Bulk API 2.0 : charger de gros volumes de données efficacement

Quand il s'agit de charger des millions d'enregistrements dans Salesforce ou Data Cloud, l'API REST classique et même l'Ingestion API montrent vite leurs limites. Bulk API 2.0 est conçue précisément pour ce cas d'usage : elle traite les opérations en asynchrone, gère automatiquement le batching interne et optimise le débit sans que le client ait à découper manuellement les fichiers. Voici comment l'utiliser correctement en environnement de production.

Pourquoi Bulk API 2.0 plutôt que l'API REST standard

L'API REST (ou SOAP) traite les enregistrements en synchrone, avec une limite pratique autour de 200 records par appel pour rester performant. Au-delà de quelques dizaines de milliers de lignes, les temps de traitement, le nombre d'appels HTTP et le risque de timeout deviennent ingérables. Bulk API 2.0 répond à ce problème avec une approche différente :

• Le client envoie un fichier CSV complet (jusqu'à 150 Mo) en un ou plusieurs uploads.
• Salesforce découpe automatiquement ce fichier en batches internes de 10 000 enregistrements.
• Le traitement est asynchrone : on interroge le job à intervalle régulier plutôt que d'attendre une réponse bloquante.

Contrairement à Bulk API 1.0, la version 2.0 supprime la nécessité de gérer soi-même le découpage en batches — c'est la principale simplification opérationnelle.

Cycle de vie d'un job Bulk

Un chargement via Bulk API 2.0 suit toujours la même séquence d'appels REST :

1. Création du job : POST /services/data/v60.0/jobs/ingest avec l'objet cible, l'opération (insert, update, upsert, delete) et le format CSV.
2. Upload des données : PUT /services/data/v60.0/jobs/ingest/{jobId}/batches avec le contenu CSV en corps de requête (content-type text/csv).
3. Clôture du job : PATCH avec "state": "UploadComplete" pour signaler que tous les batches ont été envoyés et déclencher le traitement.
4. Suivi du statut : polling périodique sur GET /jobs/ingest/{jobId} jusqu'à obtenir JobComplete ou Failed.
5. Récupération des résultats : téléchargement séparé des enregistrements réussis (successfulResults) et échoués (failedResults).

POST /services/data/v60.0/jobs/ingest
{
  "object": "Contact",
  "operation": "upsert",
  "externalIdFieldName": "External_Id__c",
  "contentType": "CSV",
  "lineEnding": "LF"
}

Choisir la bonne opération

Le choix de l'opération conditionne directement les performances et la sécurité du chargement :

• insert : le plus rapide, mais génère des doublons si le fichier est rejoué.
• upsert : nécessite un champ External ID indexé — indispensable pour les chargements idempotents et rejouables.
• update : requiert l'Id Salesforce natif, donc une extraction préalable.
• delete / hardDelete : à manier avec une extrême prudence, hardDelete contourne la corbeille.

Toujours indexer le champ External ID utilisé pour l'upsert (case "External ID" cochée sur le champ). Sans index, les performances d'upsert se dégradent fortement au-delà de quelques centaines de milliers de lignes.

Dimensionner et paralléliser les jobs

Bulk API 2.0 gère l'ordonnancement interne des batches, mais plusieurs leviers restent sous votre contrôle :

• Diviser un très gros fichier (plusieurs millions de lignes) en plusieurs jobs distincts pour paralléliser sur plusieurs threads client, en respectant les limites de concurrence de l'org (généralement 5 jobs actifs simultanés en édition Enterprise).
• Désactiver temporairement les triggers, validation rules et workflows non essentiels sur l'objet cible pendant le chargement, via une Custom Metadata Type ou un Feature Toggle, pour réduire la charge CPU côté plateforme.
• Surveiller les API limits quotidiennes de l'org : chaque batch de 10 000 lignes ne consomme qu'un seul appel API, ce qui rend Bulk API 2.0 très économe comparé à des appels REST unitaires.

Traiter les erreurs et rejeux

Un job Bulk peut se terminer avec le statut JobComplete même si une partie des lignes a échoué : la réussite du job ne garantit pas la réussite de chaque enregistrement. Il faut systématiquement :

1. Télécharger le CSV failedResults, qui contient une colonne sf__Error décrivant la cause (validation rule, duplicate rule, type mismatch...).
2. Isoler les lignes en échec pour un rejeu ciblé, plutôt que de renvoyer tout le fichier.
3. Journaliser le jobId et les métriques (nombre traité, réussi, échoué) pour audit et alerting.

Pour de l'ingestion Data Cloud spécifiquement, Bulk API 2.0 s'utilise aussi côté Ingestion API sous forme de "bulk ingestion jobs", suivant le même cycle de vie, ce qui permet de charger des DLO volumineux sans saturer les endpoints synchrones. C'est l'option à privilégier pour toute reprise d'historique (data migration) avant de basculer en flux incrémental via CDC ou streaming.