Extracción de actividades en lotes

Referencia de extremo de extracción de actividades en lotes

Las API de REST de extracción masiva recuperan grandes volúmenes de datos de actividad de Marketo. Utilice estas API para procesos que no requieran baja latencia, como integración CRM, ETL, almacenamiento de datos y archivado de datos.

Permisos

El usuario de la API debe tener el permiso “Actividad de solo lectura” o “Actividad de lectura-escritura”.

Filtros

primaryAttributeValueIds, opciones primaryattributevalueids-options

Si usa primaryAttributeValueIds, también debe incluir el filtro activityTypeIds. Este filtro solo puede contener ID de actividad que coincidan con el grupo de recursos correspondiente. Por ejemplo, al filtrar recursos de formularios web, activityTypeIds solo puede contener el ID de tipo de actividad “Rellenar formulario”.

La siguiente solicitud incluye el 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
    ]
  }
}

primaryAttributeValueIds y primaryAttributeValues no se pueden usar juntos.

primaryAttributeValues, opciones primaryattributevalues-options

Utilice la notación <program>.<asset> para especificar nombres para los grupos de recursos Programa de marketing, Lista estática y Formulario web. Por ejemplo, especifique el formulario “MPS saliente” en el programa “GL_OP_ALL_2021” como “GL_OP_ALL_2021.MPS saliente”.

La siguiente solicitud incluye el 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"
    ]
  }
}

Si usa primaryAttributeValues, también debe incluir el filtro activityTypeIds. Este filtro solo puede contener ID de actividad que coincidan con el grupo de recursos correspondiente. Por ejemplo, al filtrar recursos de formularios web, activityTypeIds solo puede contener el ID de tipo de actividad “Rellenar formulario”.

primaryAttributeValues y primaryAttributeValueIds no se pueden usar juntos.

Opciones

Creación de un trabajo

Cree un trabajo de exportación para definir los registros que desea recuperar. Use el extremo Crear trabajo de actividad de exportación.

Cada trabajo requiere un filtro createdAt. Sus parámetros datetime startAt y endAt definen las fechas de creación de actividades permitidas más tempranas y más recientes. Para excluir los tipos de actividades que no son relevantes, incluya también el filtro activityTypeIds opcional.

La siguiente solicitud crea un trabajo de exportación de CSV para los tipos de actividad seleccionados dentro de un intervalo de fechas:

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 respuesta devuelve un exportId y el estado “Creado”. Un trabajo creado aún no está en la cola de procesamiento.

Para agregar el trabajo a la cola, llame al extremo Trabajo de actividad de exportación en cola con exportId desde la respuesta de creación.

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

El estado de la respuesta ahora es “En cola”. Cuando un trabajador está disponible, el estado cambia a “Procesando” y el trabajo comienza a agregar registros desde Marketo.

Estado del trabajo de sondeo

El estado del trabajo solo se puede recuperar para trabajos creados por el mismo usuario de API.

La extracción masiva de actividades procesa los trabajos de forma asíncrona. Encuesta el punto de conexión Obtener estado del trabajo de actividad de exportación para determinar cuándo se ha completado un trabajo:

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

El campo status devuelve uno de los siguientes valores:

Recuperación de datos

Cuando el estado del trabajo sea “Completado”, recupere los datos exportados con el punto de conexión Obtener archivo de actividad de exportación:

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

El cuerpo de respuesta contiene el archivo en el formato configurado para el trabajo.

Si un campo de actividad solicitado no contiene datos, null aparece en el campo de archivo de exportación correspondiente. El siguiente ejemplo muestra los datos de actividad exportados:

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

Para la recuperación parcial o reanudable, el extremo del archivo admite el encabezado HTTP Range opcional con un intervalo de bytes. Si omite este encabezado, el extremo devolverá todo el archivo. Para obtener más información sobre el uso del encabezado Range, consulte Extracción en lotes.

Cancelación de un trabajo

Para detener un trabajo innecesario o configurado incorrectamente, llame al extremo Cancelar trabajo de actividad de exportación:

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

El estado de respuesta indica que el trabajo se ha cancelado.