Conexión de API HTTP

Información general

El destino de la API HTTP es un Adobe Experience Platform destino de flujo continuo que le ayuda a enviar datos de perfil a extremos HTTP de terceros.

Para enviar datos de perfil a extremos HTTP, primero debe conectarse al destino en Adobe Experience Platform.

Casos de uso

El destino de la API HTTP le permite exportar datos de perfil XDM y segmentos de audiencia a extremos HTTP genéricos. Aquí puede ejecutar sus propios análisis o realizar cualquier otra operación que necesite en datos de perfil exportados fuera del Experience Platform.

Los extremos HTTP pueden ser sistemas propios de los clientes o soluciones de terceros.

Tipo de exportación y frecuencia

Consulte la tabla siguiente para obtener información sobre el tipo y la frecuencia de exportación de destino.

Requisitos previos

Para utilizar el destino de la API HTTP para exportar datos fuera del Experience Platform, debe cumplir los siguientes requisitos previos:

• Debe tener un extremo HTTP que admita la API de REST.
• El extremo HTTP debe admitir el esquema de perfil del Experience Platform. No se admite ninguna transformación en un esquema de carga útil de terceros en el destino de API HTTP. Consulte la datos exportados para ver un ejemplo del esquema de salida del Experience Platform.
• El extremo HTTP debe admitir encabezados.

LISTA DE PERMITIDOS de direcciones IP

Para cumplir los requisitos de seguridad y cumplimiento de los clientes, Experience Platform proporciona una lista de IP estáticas que puede lista de permitidos para el destino de la API HTTP. Consulte LISTA DE PERMITIDOS de direcciones IP para destinos de flujo continuo para obtener la lista completa de las direcciones IP a lista de permitidos.

Tipos de autenticación compatibles

El destino de la API HTTP admite varios tipos de autenticación en el extremo HTTP:

• extremo HTTP sin autenticación;
• Autenticación del token del portador;
• Credenciales de cliente de OAuth 2.0 autenticación con el formulario de cuerpo, con client ID, client secret y grant type en el cuerpo de la solicitud HTTP, como se muestra en el ejemplo siguiente.

curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'

• Credenciales de cliente de OAuth 2.0 con autorización básica, con un encabezado de autorización que contiene la dirección URL codificada client ID y client secret.

curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'

• Concesión de contraseña de OAuth 2.0.

Conectarse al destino

Para conectarse a este destino, siga los pasos descritos en la sección tutorial de configuración de destino. Al conectarse a este destino, debe proporcionar la siguiente información:

Información de autenticación

Autenticación de token del portador

Si selecciona la opción Token portador tipo de autenticación para conectarse al extremo HTTP, introduzca los campos siguientes y seleccione Conectarse al destino:

• Token portador: inserte el token al portador para autenticarse en su ubicación HTTP.

Sin autenticación

Si selecciona la opción Ninguna tipo de autenticación para conectarse al extremo HTTP:

Cuando seleccione esta autenticación abierta, solo deberá seleccionar Conectarse al destino y se establece la conexión con el punto final.

Autenticación de contraseña de OAuth 2

Si selecciona la opción Contraseña de OAuth 2 tipo de autenticación para conectarse al extremo HTTP, introduzca los campos siguientes y seleccione Conectarse al destino:

• Dirección URL del token de acceso: Dirección URL de su lado que emite acceso a tokens y, opcionalmente, actualice los tokens.
• ID de cliente: La variable client ID que su sistema asigna a Adobe Experience Platform.
• Secreto del cliente: La variable client secret que su sistema asigna a Adobe Experience Platform.
• Nombre de usuario: El nombre de usuario para acceder al extremo HTTP.
• Contraseña: La contraseña para acceder al extremo HTTP.

Autenticación de credenciales de cliente de OAuth 2

Si selecciona la opción Credenciales de cliente de OAuth 2 tipo de autenticación para conectarse al extremo HTTP, introduzca los campos siguientes y seleccione Conectarse al destino:

• Dirección URL del token de acceso: Dirección URL de su lado que emite acceso a tokens y, opcionalmente, actualice los tokens.
• ID de cliente: La variable client ID que su sistema asigna a Adobe Experience Platform.
• Secreto del cliente: La variable client secret que su sistema asigna a Adobe Experience Platform.
• Tipo de credenciales de cliente: Seleccione el tipo de concesión de credenciales de cliente de OAuth2 que admita el punto final:
  • Formulario de cuerpo codificado: En este caso, la variable client ID y client secret se incluyen en el cuerpo de la solicitud enviado a su destino. Para ver un ejemplo, consulte la Tipos de autenticación compatibles para obtener más información.
  • Autorización básica: En este caso, la variable client ID y client secret se incluyen en un Authorization header después de ser codificado base64 y enviado a su destino. Para ver un ejemplo, consulte la Tipos de autenticación compatibles para obtener más información.

Rellenar detalles de destino

Para configurar los detalles del destino, rellene los campos opcionales y requeridos a continuación. Un asterisco junto a un campo en la interfaz de usuario indica que el campo es obligatorio.

• Nombre: Escriba un nombre por el cual reconozca este destino en el futuro.
• Descripción: Escriba una descripción que le ayudará a identificar este destino en el futuro.
• Encabezados: Introduzca los encabezados personalizados que desea incluir en las llamadas de destino, siguiendo este formato: header1:value1,header2:value2,...headerN:valueN.
• Extremo HTTP: Dirección URL del extremo HTTP al que desea enviar los datos de perfil.
• Parámetros de consulta: De forma opcional, puede agregar parámetros de consulta a la dirección URL del extremo HTTP. Dé este formato a los parámetros de consulta que utilice: parameter1=value&parameter2=value.
• Incluir nombres de segmentos: Alterne si desea que la exportación de datos incluya los nombres de los segmentos que está exportando. Para ver un ejemplo de exportación de datos con esta opción seleccionada, consulte la Datos exportados más abajo.
• Incluir marcas de hora de segmentos: Alterne si desea que la exportación de datos incluya la marca de tiempo UNIX cuando se crearon y actualizaron los segmentos, así como la marca de tiempo UNIX cuando los segmentos se asignaron al destino para la activación. Para ver un ejemplo de exportación de datos con esta opción seleccionada, consulte la Datos exportados más abajo.

Habilitar alertas

Puede activar las alertas para recibir notificaciones sobre el estado del flujo de datos a su destino. Seleccione una alerta de la lista para suscribirse y recibir notificaciones sobre el estado de su flujo de datos. Para obtener más información sobre las alertas, consulte la guía de suscripción a alertas de destinos mediante la interfaz de usuario.

Cuando haya terminado de proporcionar detalles para la conexión de destino, seleccione Siguiente.

Activar segmentos en este destino

Consulte Activar datos de audiencia en destinos de exportación de perfil de flujo continuo para obtener instrucciones sobre la activación de segmentos de audiencia en este destino.

Atributos de destino

En el Seleccionar atributos paso, Adobe recomienda seleccionar un identificador único de su esquema de unión. Seleccione el identificador único y cualquier otro campo XDM que desee exportar al destino.

Comportamiento de exportación del perfil

Experience Platform optimiza el comportamiento de exportación del perfil al destino de la API HTTP para exportar solo los datos al extremo de la API cuando se hayan producido actualizaciones relevantes en un perfil tras la calificación del segmento u otros eventos significativos. Los perfiles se exportan al destino en las siguientes situaciones:

• La actualización de perfil se determinó mediante un cambio en la pertenencia a segmentos para al menos uno de los segmentos asignados al destino. Por ejemplo, el perfil se ha clasificado para uno de los segmentos asignados al destino o ha salido de uno de los segmentos asignados al destino.
• La actualización de perfil se determinó mediante un cambio en la variable mapa de identidad. Por ejemplo, un perfil que ya se había clasificado para uno de los segmentos asignados al destino se ha añadido una nueva identidad en el atributo de mapa de identidad.
• La actualización de perfil se determinó mediante un cambio en los atributos de al menos uno de los atributos asignados al destino. Por ejemplo, uno de los atributos asignados al destino en el paso de asignación se agrega a un perfil.

En todos los casos descritos anteriormente, solo los perfiles en los que se han producido actualizaciones relevantes se exportan a su destino. Por ejemplo, si un segmento asignado al flujo de destino tiene cien miembros y cinco perfiles nuevos cumplen los requisitos para el segmento, la exportación a su destino es incremental y solo incluye los cinco perfiles nuevos.

Tenga en cuenta que todos los atributos asignados se exportan para un perfil, independientemente de dónde estén los cambios. Por lo tanto, en el ejemplo anterior, todos los atributos asignados para esos cinco perfiles nuevos se exportan incluso si los atributos en sí no han cambiado.

Qué determina una exportación de datos y qué se incluye en la exportación

En cuanto a los datos exportados para un perfil determinado, es importante comprender los dos conceptos diferentes de qué determina una exportación de datos a su destino de API HTTP y qué datos se incluyen en la exportación.

Por ejemplo, considere este flujo de datos a un destino HTTP donde se seleccionan tres segmentos en el flujo de datos y se asignan cuatro atributos al destino.

Una exportación de perfil al destino se puede determinar mediante un perfil que cumpla los requisitos de uno de los tres segmentos asignados. Sin embargo, en la exportación de datos, en la variable segmentMembership (consulte Datos exportados a continuación), podrían aparecer otros segmentos sin asignar, si ese perfil en particular es miembro de ellos y si comparten la misma política de combinación que el segmento que activó la exportación. Si un perfil cumple los requisitos para la variable Cliente con Autos DeLorean pero también es miembro de Visto "De vuelta al futuro" película y Seguidores de ciencia ficción estos otros dos segmentos también estarán presentes en la variable segmentMembership de la exportación de datos, aunque no estén asignados en el flujo de datos, si comparten la misma política de combinación con la variable Cliente con Autos DeLorean segmento.

Desde el punto de vista de los atributos de perfil, cualquier cambio en los cuatro atributos asignados arriba determinará una exportación de destino y cualquiera de los cuatro atributos asignados presentes en el perfil estará presente en la exportación de datos.

Relleno de datos históricos

Cuando agrega un segmento nuevo a un destino existente, o cuando crea un destino nuevo y le asigna segmentos, el Experience Platform exporta los datos históricos de clasificación de segmentos al destino. Perfiles que cumplen los requisitos del segmento before el segmento se agregó al destino se exporta al destino en aproximadamente una hora.

Datos exportados

Su exportación Experience Platform los datos llegan a su HTTP destino en formato JSON. Por ejemplo, la exportación siguiente contiene un perfil que se ha clasificado para un determinado segmento, es miembro de otros dos segmentos y salió de otro segmento. La exportación también incluye el nombre del atributo de perfil, los apellidos, la fecha de nacimiento y la dirección de correo electrónico personal. Las identidades de este perfil son ECID y correo electrónico.

{
  "person": {
    "birthDate": "YYYY-MM-DD",
    "name": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "personalEmail": {
    "address": "john.doe@acme.com"
  },
  "segmentMembership": {
   "ups":{
      "7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
         "lastQualificationTime":"2022-01-11T21:24:39Z",
         "status":"exited"
      },
      "59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
         "lastQualificationTime":"2022-01-02T23:37:33Z",
         "status":"existing"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"existing"
      },
      "5114d758-ce71-43ba-b53e-e2a91d67b67f":{
         "lastQualificationTime":"2022-01-11T23:37:33Z",
         "status":"realized"
      }
   }
},
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

A continuación se muestran más ejemplos de datos exportados, según la configuración de la interfaz de usuario que seleccione en el flujo de destino de conexión para Incluir nombres de segmentos y Incluir marcas de hora de segmentos opciones:

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          }
        }
      }

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

Límites y política de reintentos

En el 95 % de las veces, el Experience Platform intenta ofrecer una latencia de rendimiento inferior a 10 minutos para los mensajes enviados correctamente con una tasa inferior a 10 000 solicitudes por segundo para cada flujo de datos a un destino HTTP.

En caso de que haya solicitudes fallidas en el destino de la API HTTP, el Experience Platform almacena las solicitudes fallidas y los reintentos dos veces para enviar las solicitudes al extremo.

Recursos de Business.Adobe.com