Extracción de actividades en lotes

Referencia de extremo de extracción masiva de actividades

El conjunto de API de REST de extracción masiva de actividades proporciona una interfaz de programación para recuperar grandes cantidades de datos de actividad de Marketo.  Para casos que no requieren baja latencia y deben transferir volúmenes significativos de datos de actividad fuera de Marketo, como integración de CRM, ETL, almacenamiento de datos y archivado de datos.

Permisos

Las API de extracción masiva requieren que el usuario de la API tenga los permisos "Actividad de solo lectura" o "Actividad de lectura y escritura".

Filtros

primaryAttributeValueIds, opciones primaryattributevalueids-options

Al usar primaryAttributeValueIds, el filtro activityTypeIds debe estar presente y solo contener los identificadores de actividad que coincidan con el grupo de recursos correspondiente. Por ejemplo, si está filtrando recursos de formularios web, solo se permite el ID de tipo de actividad "Rellenar formulario" en activityTypeIds.

Ejemplo de cuerpo de la solicitud:

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

Tenga en cuenta que debe utilizar "<program>.Notación <asset>" para especificar el nombre de los siguientes grupos de recursos: programa de marketing, lista estática, formulario web. Por ejemplo, un formulario con el nombre "MPS saliente" que reside debajo de un programa con el nombre "GL_OP_ALL_2021" se especificaría como "GL_OP_ALL_2021.MPS saliente".

Ejemplo de cuerpo de la solicitud:

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

Al usar primaryAttributeValues, el filtro activityTypeIds debe estar presente y solo contener los identificadores de actividad que coincidan con el grupo de recursos correspondiente. Por ejemplo, si está filtrando recursos de formularios web, solo se permite el ID de tipo de actividad "Rellenar formulario" en activityTypeIds. primaryAttributeValues y primaryAttributeValueIds no se pueden usar juntos.

Opciones

Creación de un trabajo

Para exportar registros, primero debe definir el trabajo y el conjunto de registros que desea recuperar.  Cree el trabajo con el extremo Crear trabajo de actividad de exportación.  Al exportar actividades, se pueden aplicar dos filtros principales: createdAt, que siempre es obligatorio, y activityTypeIds, que es opcional.  El filtro createdAt se usa para definir un intervalo de fechas en el que se crearon las actividades, utilizando los parámetros startAt y endAt, los cuales son campos de fecha y hora, y representan la fecha de creación permitida más temprana y la fecha de creación permitida más reciente, respectivamente.  Opcionalmente, también puede filtrar solo ciertos tipos de actividades, usando el filtro activityTypeIds.  Esto resulta útil para eliminar resultados que no son relevantes para su caso de 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"
      }
   ]
}

El trabajo ahora tiene el estado "Creado", pero aún no está en la cola de procesamiento.  Para ponerlo en cola para que pueda comenzar a procesarse, llame al extremo Enqueue Export Activity Job mediante exportId desde la respuesta de estado 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"
      }
   ]
}

Ahora, el estado indica que el trabajo se ha puesto en cola.  Cuando un trabajador está disponible para este trabajo, 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 de actividades por lotes de Marketo es un extremo asincrónico, por lo que el estado del trabajo debe sondearse para determinar cuándo se ha completado el trabajo.  Encuesta usando el punto de conexión Obtener estado del trabajo de actividad de exportación de la siguiente manera:

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 de estado puede responder con uno de los siguientes valores:

Recuperación de datos

Una vez completado el trabajo, recupere los datos mediante el punto de conexión Obtener archivo de actividad de exportación.

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

La respuesta contiene un archivo con el formato que tenía el trabajo configurado. El punto final responde con el contenido del archivo.

Si un campo de posible cliente solicitado está vacío (no contiene datos), then null se coloca en el campo correspondiente del archivo de exportación.  En el ejemplo siguiente, el campo campaignId de la actividad devuelta está vacío.

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 admitir la recuperación parcial y fácil de reanudar de los datos extraídos, el extremo de archivo admite opcionalmente el encabezado HTTP Range del tipo bytes.  Si no se establece el encabezado, se devuelve todo el contenido.  Puede obtener más información sobre el uso del encabezado Range con Marketo Bulk Extract.

Cancelación de un trabajo

Si un trabajo se configuró incorrectamente o se vuelve innecesario, se puede cancelar fácilmente usando el punto de conexión 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"
      }
   ]
}

Esta respuesta tiene un estado que indica que el trabajo se ha cancelado.