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 cuatro tipos de objetos: Personas, Objetos personalizados, Compañías y Miembros del programa. La operación de registro es "insertar o actualizar" solamente, excepto para Miembros del programa que también admite la eliminación.

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.

Tipos de objetos admitidos

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

URL de ejemplo para compañías:

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

Ejemplo de URL para miembros del programa:

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

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.

Puntos de conexión

Los extremos de ingesta están disponibles para Personas, Objetos personalizados, Compañías y Miembros del programa.

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",
         "company": "Karnv"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal",
         "company": "Acme Inc"
      }
   ]
}

Respuesta

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Objetos personalizados

Punto final 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

Compañías

Extremo utilizado para sincronizar registros de empresa. Admite operaciones de creación, actualización y actualización con anulación de duplicación por ID de empresa externo o ID interno de Marketo.

Encabezados

Cuerpo de solicitud

Cada objeto de empresa de la matriz input admite los campos siguientes:

Los permisos requeridos son Read-Write Company.

Ejemplo de compañías

Solicitud

POST /subscriptions/{munchkinId}/companies

Encabezados

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

Cuerpo

{
   "action": "createOrUpdate",
   "dedupeBy": "dedupeFields",
   "input": [
      {
         "externalCompanyId": "ext-company-001",
         "company": "Acme Corporation",
         "industry": "Technology",
         "numberOfEmployees": 5000,
         "annualRevenue": 100000000
      },
      {
         "externalCompanyId": "ext-company-002",
         "company": "Globex Industries",
         "industry": "Manufacturing",
         "numberOfEmployees": 1200
      }
   ]
}

Respuesta

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Ejemplo de actualización de compañías por ID

{
   "action": "updateOnly",
   "dedupeBy": "idField",
   "input": [
      {
         "id": 12345,
         "company": "Acme Corporation (Renamed)",
         "numberOfEmployees": 5500
      }
   ]
}

Reglas de validación de compañías

Miembros del programa (Sincronización)

Punto final utilizado para sincronizar el estado de miembro del programa, agregar posibles clientes a los programas o actualizar su estado de programa.

Encabezados

Cuerpo de solicitud

Cada objeto de la matriz programs contiene:

Cada objeto de la matriz members contiene:

Los permisos requeridos son Read-Write Lead.

Ejemplo de sincronización de miembros de programa

Solicitud

POST /subscriptions/{munchkinId}/programmembers

Encabezados

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

Cuerpo

{
   "programs": [
      {
         "programId": 1001,
         "status": "Member",
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "status": "Influenced",
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

Respuesta

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

Miembros del programa sincronizan reglas de validación

Miembros del programa (eliminar)

Extremo utilizado para eliminar posibles clientes de los programas. Esto establece el estado de pertenencia del posible cliente en "Not in Program" y quita el miembro de ese programa.

Encabezados

Cuerpo de solicitud

Cada objeto de la matriz programs contiene:

Cada objeto de la matriz members contiene:

Los permisos requeridos son Read-Write Lead.

Ejemplo de eliminación de miembros del programa

Solicitud

POST /subscriptions/{munchkinId}/programmembers/delete

Encabezados

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

Cuerpo

{
   "programs": [
      {
         "programId": 1001,
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

Respuesta

HTTP/1.1 202
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Miembros del programa eliminan reglas de validación

Límites

Esta es una lista actualizada de protecciones:

Estos límites se aplican de forma uniforme a todas las personas, los objetos personalizados, las empresas y los miembros del programa. Para los miembros del programa, "objetos por solicitud" es el número total de referencias de posibles clientes en todos los programas de una sola solicitud.

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: