Extrait de lead en masse

Référence de point d’entrée d’extraction de leads en bloc

Les API REST d’extraction de leads en bloc récupèrent de grands ensembles d’enregistrements de leads/personnes dans Marketo. Vous pouvez également récupérer les prospects de manière incrémentielle en fonction de la date de création de l’enregistrement, de la mise à jour la plus récente, de l’appartenance à une liste statique ou dynamique.

Utilisez l’extraction de lead en bloc pour l’échange continu de données entre Marketo et des systèmes externes, y compris ETL, le Data Warehouse et les workflows d’archivage.

Autorisations

L’utilisateur de l’API propriétaire de la tâche doit disposer d’un rôle avec l’autorisation Lecture seule, Lecture-écriture, ou les deux autorisations.

Filtres

Les traitements d’exportation de leads prennent en charge plusieurs types de filtres. Chaque tâche d’exportation ne peut utiliser qu’un seul type de filtre.

Les filtres updatedAt, smartListName et smartListId nécessitent une infrastructure qui n’est pas disponible dans tous les abonnements.

Les types de filtres identifiés par un astérisque ne sont pas disponibles pour certains abonnements. Si un type de filtre n’est pas disponible pour votre abonnement, le point d’entrée Créer une tâche d’exportation de prospect renvoie l’erreur « 1035, Unsupported filter type for target subscription » (Type de filtre non pris en charge pour l’abonnement cible). Contactez l’assistance Marketo pour activer cette fonctionnalité dans le cadre de votre abonnement.

Options

Le point d’entrée Créer une tâche d’exportation principale fournit des options pour sélectionner les champs exportés, renommer les en-têtes de colonne et définir le format du fichier.

Création d’un traitement

Utilisez le point d’entrée Créer une tâche d’exportation principale pour définir une tâche d’exportation. Indiquez le fields à exporter, un type de filter et ses paramètres, le format de fichier et les noms d’en-tête de colonne personnalisés.

POST /bulk/v1/leads/export/create.json

{
   "fields": [
      "firstName",
      "lastName",
      "id",
      "email"
   ],
   "format": "CSV",
   "columnHeaderNames": {
      "firstName": "First Name",
      "lastName": "Last Name",
      "id": "Marketo Id",
      "email": "Email Address"
   },
   "filter": {
      "createdAt": {
         "startAt": "2017-01-01T00:00:00Z",
         "endAt": "2017-01-31T00:00:00Z"
      }
   }
}

Cette requête crée une tâche d’exportation pour les prospects créés entre le 1er janvier 2017 et le 31 janvier 2017. L’exportation inclut des valeurs des champs firstName, lastName, id et email.

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Created",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

La réponse confirme que le traitement est créé, mais pas démarré. Pour démarrer la tâche, appelez le point d’entrée Mettre en file d’attente la tâche d’exportation principale avec le exportId de la réponse de création.

POST /bulk/v1/leads/export/{exportId}/enqueue.json

{
    "requestId": "147e4#16b24d9b913",
    "result": [
        {
            "exportId": "fad2cd1b-e822-4025-be1e-9caa9cf1d4b8",
            "format": "CSV",
            "status": "Queued",
            "createdAt": "2019-06-04T23:35:43Z",
            "queuedAt": "2019-06-04T23:36:17Z"
        }
    ],
    "success": true
}

La réponse mise en file d’attente a le status « En file d’attente ». Lorsqu’un emplacement d’exportation devient disponible, le statut passe à « Traitement ».

Interroger le statut de la tâche

Vous ne pouvez récupérer le statut que pour les tâches créées par le même utilisateur de l’API.

Les traitements d’exportation de leads s’exécutent de manière asynchrone. Interrogez le point d’entrée Obtenir le statut de la tâche d’exportation du prospect pour suivre la progression de la tâche.

Le statut est mis à jour une seule fois toutes les 60 secondes. N’effectuez pas de sondage plus fréquemment ; dans presque tous les cas, cet intervalle est toujours excessif.

GET /bulk/v1/leads/export/{exportId}/status.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Processing",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

Cette réponse indique que la tâche est toujours en cours de traitement et que le fichier n’est donc pas disponible. Lorsque le statut de la tâche passe à « Terminé », le fichier est prêt à être téléchargé.

Le champ status peut renvoyer l’une des valeurs suivantes :

Récupération de vos données

Pour récupérer une exportation de prospect terminée, appelez le point d’entrée Obtenir le fichier de prospect d’exportation avec la exportId .

GET /bulk/v1/leads/export/{exportId}/file.json

Le corps de la réponse contient le fichier au format configuré pour la tâche.

Si un champ de prospect demandé ne contient aucune donnée, le champ correspondant dans le fichier d’exportation contient null. Dans l’exemple suivant, le prospect renvoyé a un champ d’e-mail vide.

firstName,lastName,email,cookies
Russell,Wilson,null,_mch-localhost-1536605780000-12105

Pour une récupération partielle ou pouvant être reprise, le point d’entrée du fichier prend en charge l’en-tête Range HTTP facultatif avec le type de bytes . Si vous ne définissez pas l’en-tête , le point d’entrée renvoie tout le contenu. En savoir plus sur l’utilisation de l’en-tête Range avec Marketo Extraction en bloc.

Annulation d’un traitement

Pour annuler une tâche incorrectement configurée ou inutile, appelez le point d’entrée Annuler la tâche d’exportation du prospect.

POST /bulk/v1/leads/export/{exportId}/cancel.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Cancelled",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "format": "CSV"
      }
   ]
}

La réponse confirme l’annulation du traitement.