API de ingesta de datos

La API de ingesta de datos es un servicio de alto volumen, baja latencia y alta disponibilidad diseñado para gestionar de forma eficaz y con mínimos retrasos la ingesta de grandes cantidades de datos relacionados con personas y personas.

Los datos se incorporan enviando solicitudes que se ejecutan de forma asíncrona. El estado de la solicitud se puede recuperar mediante la suscripción a eventos de Marketo Observability Data Stream.

Las interfaces se ofrecen para dos tipos de objetos: Personas y Objetos personalizados. La operación de registro es sólo "insertar o actualizar".

Autenticación

La API de ingesta de datos utiliza el mismo método de autenticación OAuth 2.0 que la API de REST de Marketo para generar un token de acceso, pero este debe pasarse a través del encabezado HTTP X-Mkto-User-Token. No se puede pasar el token de acceso a través de un parámetro de consulta.

Ejemplo de token de acceso mediante encabezado:

X-Mkto-User-Token: 11606815-aa7a-405a-80a1-f9683efa528b:ab

Permisos

La ingesta de datos utiliza el mismo modelo de permisos que la API de REST de Marketo y no requiere ningún permiso especial adicional para su uso, aunque se requieren permisos específicos para cada extremo.

Encabezados

La ingesta de datos utiliza los siguientes encabezados HTTP personalizados.

Solicitud

Respuesta

Solicitudes

Utilice el método HTTP POST para enviar datos al servidor.

La representación de datos se incluye en el cuerpo de la solicitud como application/json.

El nombre de dominio es: mkto-ingestion-api.adobe.io

La ruta de acceso comienza por /subscriptions/MunchkinId, donde MunchkinId es específico de la instancia de Marketo. Puede encontrar su Munchkin ID en la interfaz de usuario de Marketo Engage en Administración > Mi cuenta > Información de asistencia. El resto de la ruta se utiliza para especificar el recurso de interés.

Ejemplo de URL para personas:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/persons

Ejemplo de URL para objetos personalizados:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/customobjects/purchases

Respuestas

Todas las respuestas devuelven un identificador de solicitud único a través del encabezado X-Request-Id.

Ejemplo de ID de solicitud mediante encabezado:

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Correcto

Cuando una llamada se realiza correctamente, se devuelve un estado 202. No se devuelve ningún cuerpo de respuesta.

Ejemplo de respuesta de éxito:

HTTP/1.1 202 Accepted
X-Request-Id: e3d92152-0fb1-444a-8f8f-29d5a2338598
Content-Length: 0
Date: Wed, 18 Oct 2023 18:56:49 GMT

Error

Cuando una llamada produce un error, se devuelve un estado que no es 202 junto con un cuerpo de respuesta con detalles de error adicionales. El cuerpo de respuesta es application/json y contiene un único objeto con los miembros error_code y message.

A continuación se muestran códigos de error reutilizados de Adobe Developer Gateway.

A continuación, se muestran los códigos de error que son únicos para la API de ingesta de datos y que se componen de 3 segmentos. Los tres primeros dígitos son el estado (devuelto por Adobe Developer Gateway), seguidos de un cero "0", seguido de tres dígitos.

Reintentos

Cuando se detecta un error transitorio, el servicio reintenta la operación tres veces. El primer reintento se produce después de un periodo de espera de 5 minutos, el segundo después de 30 minutos más y, finalmente, el tercero después de 30 minutos más. Los reintentos se producen por varios motivos, principalmente cuando se agota el tiempo de espera de un servicio dependiente o cuando este no está disponible temporalmente.

Extremos

Los extremos de ingesta están disponibles para Personas y Objetos personalizados.

Personas

Punto final utilizado para actualizar registros de persona.

Encabezados

Cuerpo de solicitud

Los permisos requeridos son Read-Write Lead.

Ejemplo de personas

Solicitud

POST /subscriptions/{munchkinId}/persons

Encabezados

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Cuerpo

{
   "priority": "high",
   "partitionName": "EMEA",
   "dedupeFields": {
      "field1": "email",
      "field2": "firstName"
   },
   "persons":[
      {
         "email": "brooklyn.parker@karnv.com",
         "firstName": "Brooklyn",
         "lastName": "Parker"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal"
      }
   ]
}

Respuesta

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Objetos personalizados

Extremo utilizado para actualizar registros de objeto personalizados

Encabezados

Cuerpo de solicitud

Los permisos requeridos son Read-Write Custom Object.

Si se especifica un campo de vínculo a una persona en la solicitud y esa persona no existe, se producen varios reintentos. Si esa persona se añade durante la ventana de reintento (65 minutos), la actualización se realiza correctamente. Por ejemplo, si el campo de vínculo es correo electrónico en Persona y la opción Persona no existe, se produce un reintento.

Ejemplo de objetos personalizados

Solicitud

POST /subscriptions/{munchkinId}/customobjects/{customObjectAPIName}

Encabezados

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Cuerpo

{
   "dedupeBy": "dedupeFields",
   "priority": "high",
   "customObjects": [
      {
         "email": "brooklyn.parker@karnv.com",
         "vin": "20UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 330i",
         "year": 2003
      },
      {
         "email": "johnny.neal@yvu30.com",
         "vin": "19UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 325i",
         "year": 1989
      }
   ]
}

Respuesta

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Límites

Esta es una lista de uso de protecciones:

API de ingesta de datos frente a API de REST

Esta es una lista de diferencias entre la API de ingesta de datos y otras API de REST de Marketo: