API Data Ingestion

L’API Data Ingestion est un service à haut volume, à faible latence et à haute disponibilité conçu pour gérer l’ingestion de grandes quantités de données de personnes et de données relatives aux personnes de manière efficace et avec un délai minimal.

Les données sont ingérées en soumettant des requêtes qui s’exécutent de manière asynchrone. Le statut de la demande peut être récupéré en s’abonnant aux événements du flux de données d’observabilité 🔗.

Les interfaces sont proposées pour cinq types d’objets : personnes, objets personnalisés, entreprises, membres de programme et listes (listes statiques). L’opération d’enregistrement est « insérer ou mettre à jour » uniquement, à l’exception des membres de programme qui prennent également en charge la suppression et des listes qui prennent en charge les opérations d’ajout et de suppression.

Lisez la Documentation de l’API Data Ingestion.

Authentification

L’API Data Ingestion utilise la même méthode d’authentification OAuth 2.0 que l’API REST Marketo pour générer un jeton d’accès, mais ce dernier doit être transmis via l’en-tête HTTP X-Mkto-User-Token. Vous ne pouvez pas transmettre le jeton d’accès via un paramètre de requête.

Exemple de jeton d’accès via l’en-tête :

X-Mkto-User-Token: 11606815-aa7a-405a-80a1-f9683efa528b:ab

Autorisations

Data Ingestion utilise le même modèle d’autorisations que l’API REST Marketo et ne nécessite aucune autorisation spéciale supplémentaire à utiliser, bien que des autorisations spécifiques soient requises pour chaque point d’entrée.

Types d’objet pris en charge

En-têtes

L’ingestion de données utilise les en-têtes HTTP personnalisés suivants.

Requête

Réponse

Demandes

Utilisez la méthode HTTP POST pour envoyer des données au serveur.

La représentation des données est incluse dans le corps de la requête sous la forme application/json.

Le nom de domaine est : mkto-ingestion-api.adobe.io

Le chemin commence par /subscriptions/MunchkinId où MunchkinId est spécifique à votre instance Marketo. Votre Munchkin ID figure dans l’interface utilisateur de Marketo Engage sous Admin > Mon compte > Informations d’assistance. Le reste du chemin d’accès est utilisé pour spécifier la ressource qui vous intéresse.

Exemple d’URL pour les personnes :

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/persons

Exemple d’URL pour les objets personnalisés :

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/customobjects/purchases

Exemple d’URL pour les sociétés :

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/companies

Exemple d’URL pour les membres du programme :

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/programmembers

Exemple d’URL pour les listes :

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/lists

Réponses

Toutes les réponses renvoient un identifiant de requête unique via l’en-tête X-Request-Id.

Exemple d’identifiant de requête via l’en-tête :

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Réussite

Lorsqu’un appel réussit, un statut 202 est renvoyé. Aucun corps de réponse n’est renvoyé.

Exemple de réponse de succès :

HTTP/1.1 202 Accepted
X-Request-Id: e3d92152-0fb1-444a-8f8f-29d5a2338598
Content-Length: 0
Date: Wed, 18 Oct 2023 18:56:49 GMT

Erreur

Lorsqu’un appel génère une erreur, un statut non 202 est renvoyé avec un corps de réponse contenant des détails d’erreur supplémentaires. Le corps de la réponse est application/json et contient un seul objet avec les membres error_code et message.

Vous trouverez ci-dessous les codes d’erreur réutilisés de la passerelle Adobe Developer.

Vous trouverez ci-dessous les codes d’erreur propres à l’API Data Ingestion et composés de 3 segments. Les trois premiers chiffres correspondent au statut (renvoyé par la passerelle Adobe Developer), suivis d’un zéro « 0 », suivi de trois chiffres.

Reprises

Lorsqu’une erreur transitoire est détectée, le service tente à nouveau l’opération. Les reprises se produisent pour diverses raisons, principalement lorsqu’un service dépendant expire ou n’est temporairement pas disponible.

Intervalles de nouvelles tentatives :

Points d’entrée

Les points d’entrée d’ingestion sont disponibles pour les personnes, les objets personnalisés, les entreprises, les membres de programme et les listes.

Personnes

Point d’entrée utilisé pour mettre à jour les enregistrements de personne.

En-têtes

Corps de la requête

Les autorisations requises sont Read-Write Lead.

Exemple de personnes

Requête

POST /subscriptions/{munchkinId}/persons

En-têtes

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Corps

{
   "priority": "high",
   "partitionName": "EMEA",
   "dedupeFields": {
      "field1": "email",
      "field2": "firstName"
   },
   "persons":[
      {
         "email": "brooklyn.parker@karnv.com",
         "firstName": "Brooklyn",
         "lastName": "Parker",
         "company": "Karnv"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal",
         "company": "Acme Inc"
      }
   ]
}

Réponse

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Objets personnalisés

Point d’entrée utilisé pour mettre à jour les enregistrements d’objets personnalisés.

En-têtes

Corps de la requête

Les autorisations requises sont Read-Write Custom Object.

Si un champ de lien vers une Personne est spécifié dans la requête et que cette Personne n’existe pas, plusieurs reprises se produisent. Si cette personne est ajoutée pendant la fenêtre de nouvelle tentative (65 minutes), la mise à jour est réussie. Par exemple, si le champ Lien est email sur Personne et que Personne n’existe pas, des reprises ont lieu.

Exemple d’objets personnalisés

Requête

POST /subscriptions/{munchkinId}/customobjects/{customObjectAPIName}

En-têtes

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Corps

{
   "dedupeBy": "dedupeFields",
   "priority": "high",
   "customObjects": [
      {
         "email": "brooklyn.parker@karnv.com",
         "vin": "20UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 330i",
         "year": 2003
      },
      {
         "email": "johnny.neal@yvu30.com",
         "vin": "19UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 325i",
         "year": 1989
      }
   ]
}

Réponse

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Sociétés

Point d’entrée pour la synchronisation des enregistrements d’entreprise. Prend en charge les opérations de création, de mise à jour et d’upsert avec déduplication par un ID de société externe ou un ID interne Marketo.

En-têtes

Corps de la requête

Chaque objet société du tableau input prend en charge les champs suivants :

Les autorisations requises sont Read-Write Company.

Exemple de sociétés

Requête

POST /subscriptions/{munchkinId}/companies

En-têtes

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Corps

{
   "action": "createOrUpdate",
   "dedupeBy": "dedupeFields",
   "input": [
      {
         "externalCompanyId": "ext-company-001",
         "company": "Acme Corporation",
         "industry": "Technology",
         "numberOfEmployees": 5000,
         "annualRevenue": 100000000
      },
      {
         "externalCompanyId": "ext-company-002",
         "company": "Globex Industries",
         "industry": "Manufacturing",
         "numberOfEmployees": 1200
      }
   ]
}

Réponse

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Exemple de mise à jour des sociétés par ID

{
   "action": "updateOnly",
   "dedupeBy": "idField",
   "input": [
      {
         "id": 12345,
         "company": "Acme Corporation (Renamed)",
         "numberOfEmployees": 5500
      }
   ]
}

Règles de validation des sociétés

Membres du programme (synchronisation)

Point d’entrée utilisé pour synchroniser le statut des membres du programme, ajouter des leads aux programmes ou mettre à jour leur statut de programme.

En-têtes

Corps de la requête

Chaque objet du tableau de programs contient :

Chaque objet du tableau de members contient :

Les autorisations requises sont Read-Write Lead.

Exemple de synchronisation des membres du programme

Requête

POST /subscriptions/{munchkinId}/programmembers

En-têtes

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Corps

{
   "programs": [
      {
         "programId": 1001,
         "status": "Member",
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "status": "Influenced",
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

Réponse

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

Règles de validation de la synchronisation des membres du programme

Membres du programme (supprimer)

Point d’entrée utilisé pour supprimer les prospects des programmes. Cela définit le statut d’abonnement du prospect sur "Not in Program" et supprime le membre de ce programme.

En-têtes

Corps de la requête

Chaque objet du tableau de programs contient :

Chaque objet du tableau de members contient :

Les autorisations requises sont Read-Write Lead.

Exemple de suppression de membres de programme

Requête

POST /subscriptions/{munchkinId}/programmembers/delete

En-têtes

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Corps

{
   "programs": [
      {
         "programId": 1001,
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

Réponse

HTTP/1.1 202
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Les membres du programme suppriment les règles de validation

Listes (Ajouter à la liste)

Point d’entrée utilisé pour ajouter des leads à une liste statique. Les prospects sont identifiés par leur ID de prospect Marketo.

En-têtes

Corps de la requête

Chaque objet du tableau d’entrée contient :

Les autorisations requises sont Read-Write Lead.

Liste ajoutée à l’exemple de liste

Requête

POST /subscriptions/{munchkinId}/lists

En-têtes

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Corps

{
   "listId": 1001,
   "leads": [
      {
         "leadId": 10001
      },
      {
         "leadId": 10002
      },
      {
         "leadId": 10003
      }
   ]
}

Réponse

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Listes ajoutées aux règles de validation de liste

Listes (supprimer de la liste)

Point d’entrée utilisé pour supprimer les prospects d’une liste statique. Les prospects sont identifiés par leur ID de prospect Marketo.

En-têtes

Corps de la requête

Chaque objet du tableau d’entrée contient :

Les autorisations requises sont Read-Write Lead.

Exemples de listes supprimées

Requête

POST /subscriptions/{munchkinId}/lists/remove

En-têtes

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Corps

{
   "listId": 1001,
   "leads": [
      {
         "leadId": 10001
      },
      {
         "leadId": 10002
      }
   ]
}

Réponse

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

Listes supprimées des règles de validation de liste

Limites

Voici une liste mise à jour des mécanismes de sécurisation :

Ces limites s’appliquent uniformément aux personnes, aux objets personnalisés, aux sociétés, aux membres de programme et aux listes. Pour les membres de programme, « objets par demande » correspond au nombre total de références de prospect dans tous les programmes dans une seule demande. Pour les listes, « objets par requête » correspond au nombre de références de prospect dans le tableau d’entrée.

API Data Ingestion et API REST

Voici une liste des différences entre l’API Data Ingestion et les autres API REST Marketo :