Extraction d’activité en bloc

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

Le jeu d’API REST d’extraction d’activité en bloc fournit une interface de programmation pour récupérer de grandes quantités de données d’activité hors de Marketo.  Pour les cas qui ne nécessitent pas de faible latence et qui doivent transférer des volumes importants de données d’activité en dehors de Marketo, comme l’intégration CRM, ETL, l’entreposage de données et l’archivage de données.

Autorisations

Les API Bulk Activity Extract nécessitent que l’utilisateur de l’API dispose des autorisations « Activité en lecture seule » ou « Activité en lecture-écriture ».

Filtres

options primaryAttributeValueIds primaryattributevalueids-options

Lors de l’utilisation de primaryAttributeValueIds, le filtre activityTypeIds doit être présent et ne contenir que les identifiants d’activité correspondant au groupe de ressources correspondant. Par exemple, si vous filtrez sur des ressources de formulaire web, seul l’identifiant de type d’activité « Remplir le formulaire » est autorisé dans activityTypeIds.

Exemple de corps de requête :

{
  "filter": {
    "createdAt": {
      "startAt": "2021-07-01T23:59:59-00:00",
      "endAt": "2021-07-02T23:59:59-00:00"
    },
    "activityTypeIds": [
      2
    ],
    "primaryAttributeValueIds": [
      16,102,95,8
    ]
  }
}

primaryAttributeValueIds et primaryAttributeValues ne peuvent pas être utilisés ensemble.

options primaryAttributeValues primaryattributevalues-options

Notez que vous devez utiliser « <program>.Notation <asset> » pour spécifier le nom des groupes de ressources suivants : Programme marketing, Liste statique, Formulaire web. Par exemple, un formulaire portant le nom « MPS Outbound » et résidant sous un programme nommé « GL_OP_ALL_2021 » est spécifié comme « GL_OP_ALL_2021.MPS Outbound ».

Exemple de corps de requête :

{
  "filter": {
    "createdAt": {
      "startAt": "2021-07-01T23:59:59-00:00",
      "endAt": "2021-07-02T23:59:59-00:00"
    },
    "activityTypeIds": [
      2
    ],
    "primaryAttributeValues": [
      "GL_OP_ALL_2021.MPS Outbound"
    ]
  }
}

Lors de l’utilisation de primaryAttributeValues, le filtre activityTypeIds doit être présent et ne contenir que les identifiants d’activité correspondant au groupe de ressources correspondant. Par exemple, si vous filtrez sur des ressources de formulaire web, seul l’identifiant de type d’activité « Remplir le formulaire » est autorisé dans activityTypeIds. primaryAttributeValues et primaryAttributeValueIds ne peuvent pas être utilisés ensemble.

Options

Création d’un traitement

Pour exporter des enregistrements, vous devez d’abord définir la tâche et le jeu d’enregistrements à récupérer.  Créez la tâche à l’aide du point d’entrée Créer une tâche d’activité d’exportation.  Lors de l’exportation d’activités, deux filtres principaux peuvent être appliqués : createdAt, qui est toujours obligatoire, et activityTypeIds, qui est facultatif.  Le filtre createdAt est utilisé pour définir une période dans laquelle les activités ont été créées, à l’aide des paramètres startAt et endAt , qui sont tous deux des champs de date et d’heure, et qui représentent respectivement la date de création autorisée la plus proche et la date de création autorisée la plus récente.  Vous pouvez également filtrer uniquement certains types d’activités à l’aide du filtre activityTypeIds.  Cela s’avère utile pour supprimer les résultats qui ne sont pas pertinents pour votre cas d’utilisation.

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

{
   "format": "CSV",
   "filter": {
      "createdAt": {
         "startAt": "2017-07-01T23:59:59-00:00",
         "endAt": "2017-07-31T23:59:59-00:00"
      },
      "activityTypeIds": [
         1,
         12,
         13
      ]
   }
}

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

Le statut de la tâche est désormais « Créé », mais elle ne se trouve pas encore dans la file d’attente de traitement.  Pour le mettre en file d’attente afin qu’il puisse commencer le traitement, appelez le point d’entrée Mettre en file d’attente la tâche d’exportation à l’aide de l’exportId de la réponse de statut de création.

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

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

Désormais, le statut indique que le traitement a été mis en file d’attente.  Lorsqu’un programme de travail devient disponible pour cette tâche, le statut passe à « Traitement » et la tâche commence à agréger les enregistrements de Marketo.

Interroger le statut de la tâche

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

L’extraction d’activité en bloc Marketo est un point d’entrée asynchrone. Par conséquent, le statut de la tâche doit être interrogé pour déterminer quand la tâche est terminée.  Interrogez à l’aide du point d’entrée Obtenir le statut de la tâche d’exportation comme suit :

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

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Completed",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "startedAt": "2017-01-21T11:51:30-08:00",
         "finishedAt": "2017-01-21T12:59:30-08:00",
         "format": "CSV",
         "numberOfRecords": 15423,
         "fileSize": 12342,
         "fileChecksum": "sha256:c16514c7e80fcac5ea055dacae9617fc3c29aff5365e3743071313ce0ed2a815"
      }
   ]
}

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

Récupération de vos données

Une fois la tâche terminée, récupérez vos données à l’aide du point d’entrée Obtenir le fichier d’activité d’exportation.

GET /bulk/v1/activities/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), then null est placé dans le champ correspondant dans le fichier d’exportation.  Dans l'exemple ci-dessous, le champ campaignId de l'activité renvoyée est vide.

marketoGUID,leadId,activityDate,activityTypeId,campaignId,primaryAttributeValueId,primaryAttributeValue,attributes
783957693,5414087,2022-02-13T14:06:20Z,104,8497,1670,MembershipTest1,"{""Reason"":""Changed by Smart Campaign MembershipTestCampaignStepChoice.MembershipTestCampaignStepChoiceSetUp action Change Data Value"",""Program Member ID"":3240303,""Acquired By"":true,""Old Status"":""Not in Program"",""New Status ID"":21,""Success"":false,""New Status"":""On List"",""Old Status ID"":20}"
783958220,5414094,2022-02-13T14:08:50Z,104,17240,3569,SuccessWebCPS,"{""Program Member ID"":3240305,""Acquired By"":false,""Old Status"":""Not in Program"",""New Status ID"":6,""Success"":true,""New Status"":""Attended"",""Old Status ID"":1}"
783958306,5414094,2022-02-13T14:09:16Z,104,17240,3569,SuccessWebCPS,"{""Program Member ID"":3240305,""Acquired By"":false,""Old Status"":""Attended"",""New Status ID"":6,""Success"":false,""New Status"":""Attended"",""Old Status ID"":6}"
783961924,5316669,2022-02-13T14:27:21Z,104,11614,2333,Nurture Automation,"{""Program Member ID"":3240306,""Acquired By"":false,""Old Status"":""Not in Program"",""New Status ID"":27,""Success"":false,""New Status"":""Member"",""Old Status ID"":26}"

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 le Range d’en-tête HTTP de type bytes.  Si l’en-tête n’est pas défini, l’intégralité du contenu est renvoyée.  Vous pouvez 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 de l’activité:

POST /bulk/v1/activities/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 réponse a un statut indiquant que le traitement a été annulé.