Extrait de lead en masse

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

L’ensemble d’API REST d’extraction de lead en bloc fournit une interface de programmation pour récupérer de grands ensembles d’enregistrements de lead/personne en dehors de Marketo. En outre, il peut être utilisé pour 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 à une liste dynamique. Interface recommandée pour les cas d’utilisation qui nécessitent un échange continu de données entre Marketo et un ou plusieurs systèmes externes, à des fins d’ETL, d’entreposage de données et d’archivage.

Autorisations

Les API Bulk Lead Extract nécessitent que l’utilisateur de l’API propriétaire dispose d’un rôle avec une ou deux des autorisations Lecture seule, Lead ou Lead en lecture-écriture.

Filtres

Les prospects prennent en charge différentes options de filtre. Certains filtres, notamment les updatedAt, smartListName et smartListId, nécessitent des composants d’infrastructure supplémentaires qui n’ont pas encore été déployés sur tous les abonnements. Un seul type de filtre peut être spécifié par tâche d'exportation.

Le type de filtre n’est pas disponible pour certains abonnements. Si vous n’êtes pas disponible pour votre abonnement, vous recevez une erreur lors de l’appel du point d’entrée Créer une tâche d’exportation de lead (« 1035, Unsupported filter type for target subscription »). Les clients peuvent contacter l’assistance Marketo pour que cette fonctionnalité soit activée dans leur abonnement.

Options

Le point d’entrée Créer une tâche d’exportation principale fournit plusieurs options de mise en forme, ce qui permet à l’utilisateur d’inclure des champs particuliers dans le fichier exporté, de renommer les en-têtes de colonne de ces champs et le format du fichier exporté.

Création d’un traitement

Les paramètres de la tâche sont définis avant le lancement de l’exportation à l’aide du point d’entrée Créer une tâche d’exportation principale. Nous devons définir les fields nécessaires à l’exportation, le type de paramètres du filter, le format du fichier et les noms des en-têtes de colonne, le cas échéant.

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 commencera à exporter un ensemble de prospects créés entre le 1er janvier 2017 et le 31 janvier 2017, y compris les valeurs des champs firstName, lastName, id et email correspondants.

{
   "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"
      }
   ]
}

Cette opération renvoie une réponse de statut indiquant que la tâche a été créée. La tâche a été définie et créée, mais elle n'a pas encore été lancée. Pour ce faire, le point d’entrée Mettre en file d’attente la tâche d’exportation principale doit être appelé à l’aide de l’exportId de la réponse de statut 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
}

Cela répond par un status de « Mise en file d’attente », après quoi il est défini sur « Traitement » lorsqu’un emplacement d’exportation est disponible.

Interroger le statut de la tâche

Note: statut ne peut être récupéré que pour les tâches créées par le même utilisateur de l’API.

Puisqu’il s’agit d’un point d’entrée asynchrone, une fois la tâche créée, nous devons interroger son statut pour déterminer sa progression. Interroger à l’aide du point d’entrée Obtenir le statut de la tâche d’exportation du prospect. Le statut n’est mis à jour qu’une fois toutes les 60 secondes. Il est donc déconseillé d’utiliser une fréquence d’interrogation inférieure à cette fréquence, qui reste excessive dans presque tous les cas. Jetons un coup d'œil aux sondages.

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"
      }
   ]
}

Le point d’entrée de statut répond indiquant que la tâche est toujours en cours de traitement et que le fichier n’est donc pas encore disponible pour récupération. Une fois que le statut de la tâche est passé à « Terminé », elle a été préparée pour téléchargement.

Le champ de statut peut répondre avec l’une des options suivantes :

Récupération de vos données

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

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

La réponse contient un fichier formaté selon la configuration de la tâche. Le point d’entrée répond avec le contenu du fichier .

Si un champ de prospect demandé est vide (ne contient aucune donnée), null est placé dans le champ correspondant dans le fichier d’exportation. Dans l’exemple ci-dessous, le champ d’e-mail du prospect renvoyé est vide.

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

Pour prendre en charge la récupération partielle et conviviale des données extraites, le point d’entrée du fichier prend éventuellement en charge la plage d’en-têtes HTTP du type octets. Si l’en-tête n’est pas défini, l’intégralité du contenu est renvoyée. En savoir plus sur l’utilisation de l’en-tête de plage avec Marketo Extraction en bloc.

Annulation d’un traitement

Si une tâche n’a pas été configurée correctement ou devient inutile, elle peut facilement être annulée à l’aide du 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"
      }
   ]
}

Cette opération répond avec un statut indiquant que la tâche a été annulée.