Ingestion de données dans Data Cloud : les bases de l'API d'ingestion

L'API d'ingestion Data Cloud (Ingestion API) est le point d'entrée programmatique permettant d'envoyer des données depuis n'importe quelle source externe vers Data Cloud, sans passer par un connecteur préconstruit. Pour un data engineer, c'est l'outil à connaître dès qu'un système tiers n'est pas couvert par les connecteurs natifs (ERP maison, application interne, plateforme SaaS non référencée). Cet article pose les fondations : architecture, authentification, structure des appels et pièges à éviter.

Qu'est-ce que l'API d'ingestion Data Cloud ?

L'Ingestion API est une API REST exposée par Data Cloud qui accepte des payloads JSON structurés et les route vers un Data Lake Object (DLO) via un connecteur d'ingestion personnalisé (Ingestion Connector). Contrairement aux connecteurs Salesforce CRM ou Marketing Cloud qui répliquent automatiquement les objets natifs, l'Ingestion API exige de définir explicitement un schéma (yaml ou via l'interface Setup) qui décrit la structure des données entrantes : champs, types, clé primaire.

Une fois le schéma déployé, Data Cloud génère un connecteur dédié qui expose un endpoint HTTPS. Chaque appel à cet endpoint dépose un lot d'enregistrements dans une zone de staging avant que le pipeline d'ingestion ne les persiste dans le DLO correspondant.

Les briques de l'architecture d'ingestion

Avant d'écrire le premier appel API, il faut comprendre trois composants qui interagissent :

• Ingestion API Connector : l'objet de configuration qui définit le schéma et génère les endpoints REST.
• Data Stream : la ressource qui relie le connecteur à un DLO cible et déclenche le mapping vers le Data Model Object (DMO).
• Data Lake Object (DLO) : la table de stockage brute dans Data Cloud, avant toute transformation ou harmonisation.

Ce découpage est important car il sépare la responsabilité de "recevoir la donnée" (le connecteur) de celle de "l'interpréter métier" (le DMO, via le mapping). En pratique, on ne modifie jamais le DLO directement : on ajuste le schéma du connecteur puis on relance le data stream.

Authentification et configuration

L'authentification repose sur le protocole OAuth 2.0 avec le flow Client Credentials ou JWT Bearer, adossé à un Connected App Salesforce. Il faut récupérer un access token via l'endpoint d'autorisation avant chaque session d'ingestion, puis l'utiliser en en-tête Authorization: Bearer sur les appels suivants. Le token a une durée de vie limitée (généralement 2 heures) : tout pipeline d'ingestion doit implémenter un mécanisme de rafraîchissement automatique.

POST /services/data/v60.0/ssot/ingest/{connectorApiName}/{objectApiName}
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "data": [
    {
      "id": "CUST-10245",
      "email": "client@example.com",
      "createdDate": "2026-01-20T10:15:00Z"
    }
  ]
}

Le nom du connecteur (connectorApiName) et de l'objet (objectApiName) proviennent directement du schéma déclaré dans Setup > Data Cloud > Ingestion API. Une erreur fréquente est d'utiliser le label affiché dans l'UI plutôt que l'API name réel, ce qui provoque une erreur 404 silencieuse.

Structurer le schéma et gérer les clés

Le schéma d'un connecteur d'ingestion se définit via un fichier OpenAPI YAML ou directement dans l'assistant Setup. Chaque objet doit déclarer :

1. Un identifiant primaire (primaryKey) utilisé pour les upserts.
2. Les types de champs (string, number, date, boolean) — Data Cloud ne fait pas de conversion implicite agressive, un mauvais typage provoque des rejets.
3. Les champs obligatoires vs optionnels.

Le comportement par défaut est un upsert basé sur la clé primaire : un enregistrement existant est mis à jour, un nouveau est inséré. Il n'y a pas de suppression via l'Ingestion API — pour purger des données, il faut passer par les Data Retention Policies ou une purge manuelle du DLO.

Bonnes pratiques et pièges courants

Quelques points de vigilance qui reviennent systématiquement en mission :

• Limiter la taille des payloads à quelques centaines de records par appel : l'Ingestion API est pensée pour du near real-time, pas pour des dumps massifs (voir Bulk API 2.0 pour les gros volumes).
• Toujours vérifier le code retour HTTP et le corps de la réponse : un 202 Accepted ne garantit pas que chaque enregistrement individuel a été traité sans erreur.
• Respecter les limites de débit (rate limits) définies par l'org Data Cloud, qui varient selon l'édition — un pic d'appels non maîtrisé peut déclencher un throttling.
• Versionner les schémas : une modification de structure sur un connecteur en production peut casser les mappings DMO existants.

À retenir : l'Ingestion API n'est pas un remplaçant universel des connecteurs batch. Elle est optimale pour des flux applicatifs à fréquence modérée (webhooks, événements métier) ; pour des chargements massifs et ponctuels, préférez Bulk API 2.0.

Maîtriser ces bases permet ensuite d'aborder sereinement les sujets plus avancés : streaming via SDK, connecteurs batch automatisés, ou stratégies de transformation avant/après ingestion, qui feront l'objet des prochains articles de cette série.