Extraction d’activité en bloc

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

Les API Bulk Activity Extract REST récupèrent d’importants volumes de données d’activité dans Marketo. Utilisez ces API pour les processus qui ne nécessitent pas de faible latence, comme l’intégration CRM, ETL, l’entreposage des données et l’archivage des données.

Autorisations

L’utilisateur de l’API doit disposer de l’autorisation « Activité en lecture seule » ou « Activité en lecture-écriture ».

Filtres

options primaryAttributeValueIds primaryattributevalueids-options

Lorsque vous utilisez primaryAttributeValueIds, vous devez également inclure le filtre activityTypeIds. Ce filtre ne peut contenir que les ID d’activité correspondant au groupe de ressources correspondant. Par exemple, lors du filtrage de ressources de formulaire web, activityTypeIds ne peut contenir que l’identifiant de type d’activité « Remplir le formulaire ».

La requête suivante inclut le filtre primaryAttributeValueIds :

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

Utilisez la notation <program>.<asset> pour spécifier les noms des groupes de ressources Programme marketing, Liste statique et Formulaire web . Par exemple, spécifiez le formulaire « MPS Outbound » dans le programme « GL_OP_ALL_2021 » comme « GL_OP_ALL_2021.MPS Outbound ».

La requête suivante inclut le filtre primaryAttributeValues :

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

Lorsque vous utilisez primaryAttributeValues, vous devez également inclure le filtre activityTypeIds. Ce filtre ne peut contenir que les ID d’activité correspondant au groupe de ressources correspondant. Par exemple, lors du filtrage de ressources de formulaire web, activityTypeIds ne peut contenir que l’identifiant de type d’activité « Remplir le formulaire ».

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

Options

Création d’un traitement

Créez une tâche d’exportation pour définir les enregistrements à récupérer. Utilisez le point d’entrée Créer une tâche d’activité d’exportation.

Chaque tâche nécessite un filtre createdAt. Ses paramètres datetime startAt et endAt définissent les dates de création d’activité autorisées au plus tôt et au plus tard. Pour exclure les types d’activité qui ne sont pas pertinents, incluez également le filtre activityTypeIds facultatif.

La requête suivante crée une tâche d’exportation CSV pour les types d’activités sélectionnés au cours d’une période :

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

La réponse renvoie un exportId et un statut de « Créé ». Une tâche créée ne se trouve pas encore dans la file d’attente de traitement.

Pour ajouter la tâche à la file d’attente, appelez le point d’entrée Mettre en file d’attente la tâche d’exportation avec la exportId de la réponse 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"
      }
   ]
}

Le statut de la réponse est désormais « En file d’attente ». Lorsqu’un programme de travail est disponible, le statut passe à « Traitement » et le traitement commence à agréger les enregistrements à partir 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 traite les tâches de manière asynchrone. Interrogez le point d’entrée Obtenir le statut de la tâche d’activité d’exportation pour déterminer quand une tâche est terminée :

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 status renvoie l’une des valeurs suivantes :

Récupération de vos données

Lorsque le statut de la tâche est « Terminé », récupérez les données exportées avec le point d’entrée Obtenir le fichier d’activité d’exportation :

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

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

Si un champ d’activité demandé ne contient aucune donnée, null apparaît dans le champ du fichier d’exportation correspondant. L’exemple suivant illustre les données d’activité exportées :

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 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 une plage de bytes. Si vous omettez cet en-tête, le point d’entrée renvoie le fichier entier. Pour plus d’informations sur l’utilisation de l’en-tête Range, voir Extraction en bloc.

Annulation d’un traitement

Pour arrêter un traitement incorrectement configuré ou inutile, appelez le point d’entrée ​ Annuler le traitement de l’activité d’exportation ​ :

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

Le statut de la réponse indique que le traitement est annulé.