Estrazione attività in blocco

Riferimento endpoint estrazione attività in blocco

Il set di API REST per l’estrazione di attività in blocco fornisce un’interfaccia programmatica per recuperare grandi quantità di dati di attività da Marketo.  Per i casi che non richiedono bassa latenza e che devono trasferire volumi significativi di dati di attività al di fuori di Marketo, come l’integrazione CRM, ETL, il data warehousing e l’archiviazione dei dati.

Autorizzazioni

Le API di estrazione attività in blocco richiedono che l’utente API disponga delle autorizzazioni "Attività di sola lettura" o "Attività di lettura/scrittura".

Filtri

opzioni primaryAttributeValueIds primaryattributevalueids-options

Quando si utilizza primaryAttributeValueIds, il filtro activityTypeIds deve essere presente e contenere solo ID attività che corrispondono al gruppo di risorse corrispondente. Se ad esempio si applica un filtro alle risorse di un modulo Web, in activityTypeIds è consentito solo l'ID del tipo di attività "Compila modulo".

Esempio di corpo della richiesta:

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

Devi usare "<programma>.Notazione <asset>" per specificare il nome per i seguenti gruppi di risorse: Programma di marketing, Elenco statico, Modulo Web. Ad esempio, una maschera con il nome "MPS in uscita" che si trova sotto un programma con il nome "GL_OP_ALL_2021" viene specificata come "GL_OP_ALL_2021.MPS in uscita".

Esempio di corpo della richiesta:

{
  "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, il filtro activityTypeIds deve essere presente e contenere solo ID attività che corrispondono al gruppo di risorse corrispondente. Se ad esempio si applica un filtro alle risorse di un modulo Web, in activityTypeIds è consentito solo l'ID del tipo di attività "Compila modulo". Impossibile utilizzare primaryAttributeValues e primaryAttributeValueIds insieme.

Opzioni

Creazione di un processo

Per esportare i record, è innanzitutto necessario definire il job e il set di record che si desidera recuperare.  Crea il processo utilizzando l'endpoint Crea processo attività di esportazione.  Durante l'esportazione delle attività è possibile applicare due filtri primari: createdAt, che è sempre obbligatorio, e activityTypeIds, che è facoltativo.  Il filtro createdAt viene utilizzato per definire un intervallo di date in cui sono state create le attività, utilizzando i parametri startAt e endAt, che sono entrambi campi datetime e rappresentano rispettivamente la prima data di creazione consentita e l'ultima data di creazione consentita.  Facoltativamente, è inoltre possibile filtrare solo alcuni tipi di attività utilizzando il filtro activityTypeIds.  Ciò è utile per rimuovere risultati che non sono rilevanti per il tuo caso d’uso.

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

Il processo ora ha lo stato "Creato", ma non è ancora nella coda di elaborazione.  Per metterlo in coda in modo che possa iniziare l'elaborazione, chiamare l'endpoint Processo attività di esportazione accodamento utilizzando il valore exportId dalla risposta dello stato 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"
      }
   ]
}

Ora lo stato segnala che il processo è stato messo in coda.  Quando un processo di lavoro diventa disponibile per questo processo, lo stato viene impostato su "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 di Marketo è un endpoint asincrono, pertanto è necessario eseguire il polling dello stato del processo per determinare quando è stato completato.  Effettua il polling utilizzando l'endpoint Ottieni stato processo attività di esportazione come segue:

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 di stato può rispondere con uno dei seguenti valori:

Recupero dei dati

Una volta completato il processo, recuperare i dati utilizzando l'endpoint Get Export Activity File.

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

La risposta contiene un file formattato nel modo in cui è stato configurato il processo. L’endpoint risponde con il contenuto del file.

Se un campo lead richiesto è vuoto (non contiene dati), then null viene inserito nel campo corrispondente nel file di esportazione.  Nell'esempio seguente, il campo campaignId per l'attività restituita è vuoto.

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 supportare il recupero parziale e semplice dei dati estratti, l'endpoint del file supporta facoltativamente l'intestazione HTTP Range di tipo bytes.  Se l’intestazione non è impostata, viene restituito l’intero contenuto.  Per ulteriori informazioni sull'utilizzo dell'intestazione Range con Marketo Bulk Extract.

Annullamento di un processo

Se un processo non è stato configurato correttamente o non è più necessario, può essere facilmente annullato utilizzando l'endpoint Annulla processo attività di 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"
      }
   ]
}

La risposta presenta uno stato che indica che il processo è stato annullato.