Extracción de posibles clientes

Referencia de extremo de extracción masiva de posibles clientes

El conjunto de API de REST de extracción masiva de posibles clientes proporciona una interfaz programática para recuperar grandes conjuntos de registros de posibles clientes/personas de Marketo. Además, se puede utilizar para recuperar posibles clientes de forma incremental en función de la fecha creada del registro, la actualización más reciente, la pertenencia a una lista estática o la pertenencia a una lista inteligente. La interfaz recomendada para casos de uso que requieren un intercambio continuo de datos entre Marketo y uno o más sistemas externos, para fines de ETL, almacenamiento de datos y archivo.

Permisos

Las API de extracción masiva de posibles clientes requieren que el usuario de la API propietaria tenga una función con uno o ambos permisos de solo lectura o de lectura-escritura.

Filtros

Los posibles clientes admiten varias opciones de filtro. Algunos filtros, incluidos updatedAt, smartListName y smartListId, requieren componentes de infraestructura adicionales que aún no se han implementado en todas las suscripciones. Solo se puede especificar un tipo de filtro por trabajo de exportación.

El tipo de filtro no está disponible para algunas suscripciones. Si no está disponible para la suscripción, recibirá un error al llamar al punto final de Crear trabajo de posible cliente de exportación ("1035, Tipo de filtro no compatible para la suscripción de destino"). Los clientes pueden ponerse en contacto con el servicio de asistencia de Marketo para habilitar esta funcionalidad en su suscripción.

Opciones

El punto final Crear trabajo de posible cliente de exportación proporciona varias opciones de formato, lo que permite al usuario incluir campos concretos en el archivo exportado, cambiar el nombre de los encabezados de columna de estos campos y cambiar el formato del archivo exportado.

Creación de un trabajo

Los parámetros del trabajo se definen antes de iniciar la exportación con el punto de conexión Crear trabajo de posible cliente de exportación. Debemos definir los fields necesarios para la exportación, el tipo de parámetros de filter, format del archivo y los nombres de encabezado de columna, si los hay.

POST /bulk/v1/leads/export/create.json

{
   "fields": [
      "firstName",
      "lastName",
      "id",
      "email"
   ],
   "format": "CSV",
   "columnHeaderNames": {
      "firstName": "First Name",
      "lastName": "Last Name",
      "id": "Marketo Id",
      "email": "Email Address"
   },
   "filter": {
      "createdAt": {
         "startAt": "2017-01-01T00:00:00Z",
         "`endAt`": "2017-01-31T00:00:00Z"
      }
   }
}

Esta solicitud comenzará a exportar un conjunto de posibles clientes creados entre el 1 de enero de 2017 y el 31 de enero de 2017, incluidos los valores de los campos firstName, lastName, id y email correspondientes.

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

Devuelve una respuesta de estado que indica que el trabajo se ha creado. Se ha definido y creado el trabajo, pero aún no se ha iniciado. Para ello, se debe llamar al extremo Enqueue Export Lead Job mediante el exportId de la respuesta de estado de creación:

POST /bulk/v1/leads/export/{exportId}/enqueue.json

{
    "requestId": "147e4#16b24d9b913",
    "result": [
        {
            "exportId": "fad2cd1b-e822-4025-be1e-9caa9cf1d4b8",
            "format": "CSV",
            "status": "Queued",
            "createdAt": "2019-06-04T23:35:43Z",
            "queuedAt": "2019-06-04T23:36:17Z"
        }
    ],
    "success": true
}

Esto responde con un status de "En cola" después del cual se establecerá en "Procesando" cuando haya una ranura de exportación disponible.

Estado del trabajo de sondeo

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

Dado que este es un extremo asincrónico, después de crear el trabajo, debemos sondear su estado para determinar su progreso. Encuesta usando el punto de conexión Obtener estado del trabajo del posible cliente de exportación. El estado solo se actualiza una vez cada 60 segundos, por lo que no se recomienda una frecuencia de sondeo inferior a esta, y en casi todos los casos sigue siendo excesiva. Echemos un vistazo rápido a las encuestas.

GET /bulk/v1/leads/export/{exportId}/status.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Processing",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

El punto final de estado responde indicando que el trabajo aún se está procesando, por lo que el archivo aún no está disponible para su recuperación. Una vez que el estado del trabajo cambia a "Completado", se prepara para la descarga.

El campo de estado puede responder con cualquiera de las siguientes opciones:

Recuperación de datos

Para recuperar el archivo de una exportación de posibles clientes completada, simplemente llame al extremo Obtener archivo de posibles clientes de exportación con su exportId.

GET /bulk/v1/leads/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), null se coloca en el campo correspondiente del archivo de exportación. En el siguiente ejemplo, el campo de correo electrónico del posible cliente devuelto está vacío.

firstName,lastName,email,cookies
Russell,Wilson,null,_mch-localhost-1536605780000-12105

Para admitir la recuperación parcial y fácil de reanudar de los datos extraídos, el extremo del archivo admite opcionalmente el encabezado HTTP Range de los bytes de tipo. Si no se establece el encabezado, se devuelve todo el contenido. Obtenga más información acerca del 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 posible cliente de exportación:

POST /bulk/v1/leads/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"
      }
   ]
}

Esto responde con un estado que indica que el trabajo se ha cancelado.