Estrazione attività in blocco
Creato per:
- Amministratore
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
| Tipo di filtro | Tipo di dati | Obbligatorio | Note |
|---|---|---|---|
| createdAt | Date Range | Sì | Accetta un oggetto JSON con i membri startAt e endAt. startAt accetta un datetime che rappresenta la filigrana bassa e endAt accetta un datetime che rappresenta la filigrana alta. L’intervallo non può essere superiore a 31 giorni. I processi con questo tipo di filtro restituiscono tutti i record accessibili creati entro l'intervallo di date. I valori di data devono essere in formato ISO-8601, senza millisecondi. |
| activityTypeIds | Array[Intero] | No | Accetta un oggetto JSON con un membro, activityTypeIds. Il valore deve essere una matrice di numeri interi corrispondenti ai tipi di attività desiderati. L'attività "Elimina lead" non è supportata (utilizzare l'endpoint Ottieni lead eliminati). Recupera gli ID dei tipi di attività utilizzando l'endpoint Get Activity Types. |
| primaryAttributeValueIds | Array[Intero] | No | Accetta un oggetto JSON con un membro, primaryAttributeValueIds. Il valore è una matrice di ID che specificano gli attributi primari su cui filtrare. È possibile specificare un massimo di 50 ID. Gli ID sono l’identificatore univoco di un campo lead o di una risorsa e possono essere recuperati chiamando l’endpoint API REST appropriato. Ad esempio, per filtrare in base a un modulo specifico per l'attività "Compila modulo", passa il nome del modulo all'endpoint Ottieni modulo per nome per recuperare l'ID modulo. Di seguito è riportato un elenco di tipi di attività in cui è supportato il filtro degli attributi primari. |
| primaryAttributeValues | Array[Stringa] | No | Accetta un oggetto JSON con un membro, primaryAttributeValues. Il valore è un array di nomi che specificano gli attributi principali su cui filtrare. È possibile specificare un massimo di 50 nomi. I nomi sono l’identificatore univoco di un campo lead o di una risorsa e possono essere recuperati chiamando l’endpoint API REST appropriato. Ad esempio, per filtrare in base a un modulo specifico per l'attività "Compila modulo", passa l'ID modulo all'endpoint Ottieni modulo per ID per recuperare il nome del modulo. Di seguito è riportato un elenco di tipi di attività in cui è supportato il filtro degli attributi primari. |
opzioni primaryAttributeValueIds
| Tipo di attività | ID valore attributo principale | Endpoint di recupero | Gruppo risorse |
|---|---|---|---|
| Modifica valore dati | ID campo lead | Descrizione lead | Nome attributo |
| Modifica punteggio | ID campo lead | Descrizione lead | Nome attributo |
| Modifica stato in progressione | ID programma | Ottieni programma per nome | Programma di marketing |
| Aggiungi all’elenco | ID elenco statico | Ottieni elenco statico per nome | Elenco statico |
| Rimuovi dall’elenco | ID elenco statico | Ottieni elenco statico per nome | Elenco statico |
| Compila modulo | ID modulo | Ottieni modulo per nome | Modulo web |
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
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
createdAt. È possibile includere un filtro activityTypeIds facoltativo. I filtri vengono applicati al set di attività accessibile e il set di attività risultante viene restituito dal processo di esportazione.marketoGUIDleadId activityDate activityTypeId campaignId primaryAttributeValueId primaryAttributeValueattributes. Questo parametro può essere utilizzato per ridurre il numero di campi restituiti specificando un sottoinsieme dall'elenco precedente. Esempio:"fields": ["leadId", "activityDate", "activityTypeId"]È possibile specificare un campo aggiuntivo "actionResult" per includere l'azione dell'attività ("success", "skipped" o "failed").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:
- Creato
- In coda
- Elaborazione
- Annullato
- Completato
- Operazione non riuscita
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.