Estrazione attività in blocco

Riferimento endpoint estrazione attività in blocco

Le API REST di Bulk Activity Extract recuperano grandi volumi di dati di attività da Marketo. Utilizzare queste API per i processi che non richiedono latenza ridotta, come l’integrazione CRM, ETL, data warehousing e archiviazione dati.

Autorizzazioni

L’utente API deve disporre dell’autorizzazione “Attività di sola lettura” o “Attività di lettura/scrittura”.

Filtri

opzioni primaryAttributeValueIds primaryattributevalueids-options

Quando si utilizza primaryAttributeValueIds, è necessario includere anche il filtro activityTypeIds. Questo filtro può contenere solo ID attività che corrispondono al gruppo di risorse corrispondente. Ad esempio, quando si filtrano le risorse dei moduli Web, activityTypeIds può contenere solo l’ID del tipo di attività “Compila modulo”.

La richiesta seguente include il filtro 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
    ]
  }
}

Impossibile utilizzare primaryAttributeValueIds e primaryAttributeValues insieme.

opzioni primaryAttributeValues primaryattributevalues-options

Utilizza la notazione <program>.<asset> per specificare i nomi dei gruppi di risorse Programma di marketing, Elenco statico e Modulo web. Ad esempio, specificate la maschera “MPS in uscita” nel programma “GL_OP_ALL_2021” come “GL_OP_ALL_2021.MPS in uscita”.

La richiesta seguente include il filtro 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"
    ]
  }
}

Quando si utilizza primaryAttributeValues, è necessario includere anche il filtro activityTypeIds. Questo filtro può contenere solo ID attività che corrispondono al gruppo di risorse corrispondente. Ad esempio, quando si filtrano le risorse dei moduli Web, activityTypeIds può contenere solo l’ID del tipo di attività “Compila modulo”.

Impossibile utilizzare primaryAttributeValues e primaryAttributeValueIds insieme.

Opzioni

Creazione di un processo

Creare un processo di esportazione per definire i record da recuperare. Utilizza l’endpoint Crea processo attività di esportazione.

Ogni processo richiede un filtro createdAt. I parametri datetime startAt e endAt definiscono le date di creazione dell’attività consentite più recenti e meno recenti. Per escludere tipi di attività non rilevanti, includere anche il filtro activityTypeIds facoltativo.

La seguente richiesta crea un processo di esportazione CSV per i tipi di attività selezionati all’interno di un intervallo di date:

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 risposta restituisce un valore exportId e lo stato “Creato”. Un processo creato non è ancora nella coda di elaborazione.

Per aggiungere il processo alla coda, chiamare l’endpoint Attività di esportazione accodamento con exportId dalla risposta di creazione.

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

Lo stato della risposta ora è “In coda”. Quando un lavoratore diventa disponibile, lo stato cambia in “Elaborazione” e il processo inizia ad aggregare i record da Marketo.

Stato processo di polling

Lo stato del processo può essere recuperato solo per i processi creati dallo stesso utente API.

L’estrazione dell’attività in blocco elabora i processi in modo asincrono. Esamina l’endpoint Ottieni stato processo attività di esportazione per determinare quando un processo è completo:

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

Il campo status restituisce uno dei seguenti valori:

Recupero dei dati

Quando lo stato del processo è “Completato”, recuperare i dati esportati con l’endpoint Ottieni file attività di esportazione:

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

Il corpo della risposta contiene il file nel formato configurato per il processo.

Se un campo attività richiesto non contiene dati, null viene visualizzato nel campo export-file corrispondente. L’esempio seguente mostra i dati di attività esportati:

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

Per il recupero parziale o ripristinabile, l’endpoint del file supporta l’intestazione HTTP Range facoltativa con un intervallo bytes. Se ometti questa intestazione, l’endpoint restituisce l’intero file. Per ulteriori informazioni sull’utilizzo dell’intestazione Range, vedere Estrazione in blocco.

Annullamento di un processo

Per interrompere un processo configurato in modo errato o non necessario, chiamare l’endpoint Annulla processo attività esportazione:

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

Lo stato della risposta indica che il processo è annullato.