[Ultimate]{class="badge positive"}

Conexión de API HTTP

Información general overview

IMPORTANT
Este destino solo está disponible para los clientes de Adobe Real-time Customer Data Platform Ultimate.

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

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

Casos de uso use-cases

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

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

Audiencias compatibles supported-audiences

Esta sección describe qué tipos de audiencias puede exportar a este destino.

Origen de audiencia
Admitido
Descripción
Segmentation Service
Audiencias generadas a través del Experience Platform Servicio de segmentación.
Cargas personalizadas
Las audiencias importadas en el Experience Platform desde archivos CSV.

Tipo y frecuencia de exportación export-type-frequency

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

Elemento
Tipo
Notas
Tipo de exportación
Basado en perfil
Va a exportar todos los miembros de un segmento, junto con los campos de esquema deseados (por ejemplo: dirección de correo electrónico, número de teléfono, apellidos), tal como se eligió en la pantalla de asignación de flujo de trabajo de activación de destino.
Frecuencia de exportación
Transmisión
Los destinos de streaming son conexiones basadas en API "siempre activadas". Tan pronto como se actualiza un perfil en Experience Platform según la evaluación de audiencias, el conector envía la actualización de forma descendente a la plataforma de destino. Más información sobre destinos de streaming.

Requisitos previos prerequisites

Para utilizar el destino de la API HTTP para exportar datos fuera de 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 a un esquema de carga útil de terceros en el destino de la API HTTP. Consulte la sección datos exportados para ver un ejemplo del esquema de salida del Experience Platform.
  • El extremo HTTP debe admitir encabezados.
TIP
También puede usar Adobe Experience Platform Destination SDK para configurar una integración y enviar datos de perfil del Experience Platform a un extremo HTTP.

Compatibilidad con el protocolo mTLS y certificado mtls-protocol-support

Puede usar Mutual Transport Layer Security (mTLS) para garantizar una seguridad mejorada en las conexiones salientes a las conexiones de destino de la API HTTP.

mTLS es un método de seguridad de extremo a extremo para la autenticación mutua que garantiza que ambas partes que comparten información son quienes dicen ser antes de que se compartan los datos. mTLS incluye un paso adicional en comparación con TLS, en el cual el servidor también solicita el certificado del cliente y lo verifica al final.

Si desea usar mTLS con HTTP API destinos, la dirección de servidor que puso en la página detalles de destino debe tener los protocolos TLS deshabilitados y solamente mTLS habilitados. Si el protocolo TLS 1.2 sigue habilitado en el extremo, no se envía ningún certificado para la autenticación del cliente. Esto significa que para usar mTLS con su destino HTTP API, el extremo del servidor de "recepción" debe ser un extremo de conexión habilitado solo para mTLS.

Descargar certificado certificate

Si desea comprobar Common Name (CN) y Subject Alternative Names (SAN) para realizar una validación adicional de terceros, puede descargar el certificado a continuación:

LISTA DE PERMITIDOS de direcciones IP ip-address-allowlist

Para cumplir los requisitos de seguridad y cumplimiento de normas de los clientes, Experience Platform proporciona una lista de direcciones IP estáticas que puede lista de permitidos para el destino de la API HTTP. Consulte la lista de permitidos de direcciones IP para destinos de streaming para obtener la lista completa de direcciones IP para lista de permitidos.

Tipos de autenticación admitidos supported-authentication-types

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

  • Punto final HTTP sin autenticación;
  • Autenticación de token de portador;
  • Autenticación de credenciales de cliente OAuth 2.0 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>'
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'

Conexión al destino connect-destination

IMPORTANT
Para conectarse al destino, necesita los permisos de control de acceso de Ver destinos] y Administrar destinos[5}. Lea la descripción general del control de acceso o póngase en contacto con el administrador del producto para obtener los permisos necesarios.

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

Información de autenticación authentication-information

Autenticación de token de portador bearer-token-authentication

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

Imagen de la pantalla de la interfaz de usuario donde puede conectarse al destino de la API HTTP mediante la autenticación de token de portador.

  • Token de portador: inserte el token de portador para autenticarse en la ubicación HTTP.

Sin autenticación no-authentication

Si selecciona el tipo de autenticación None para conectarse al extremo HTTP:

Imagen de la pantalla de la interfaz de usuario donde puede conectarse al destino de la API HTTP sin utilizar autenticación.

Cuando selecciona esta apertura de autenticación, solo necesita seleccionar Conectarse al destino y se establece la conexión con su extremo.

Autenticación de contraseña de OAuth 2 oauth-2-password-authentication

Si selecciona el tipo de autenticación OAuth 2 Password para conectarse al extremo HTTP, introduzca los campos siguientes y seleccione Conectar con destino:

Imagen de la pantalla de la interfaz de usuario donde puede conectarse al destino de la API HTTP mediante OAuth 2 con autenticación de contraseña.

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

Autenticación de credenciales de cliente de OAuth 2 oauth-2-client-credentials-authentication

Si selecciona el tipo de autenticación Credenciales del cliente de OAuth 2 para conectarse al extremo HTTP, introduzca los campos siguientes y seleccione Conectar con destino:

Imagen de la pantalla de la interfaz de usuario donde puede conectarse al destino de la API HTTP mediante OAuth 2 con autenticación de credenciales de cliente.

  • URL de token de acceso: URL del lado del usuario que emite tokens de acceso y, opcionalmente, tokens de actualización.

  • ID de cliente: El client ID que su sistema asigna a Adobe Experience Platform.

  • Secreto de cliente: El 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 admitida por el extremo:

    • Formulario de cuerpo codificado: En este caso, client ID y client secret se incluyen en el cuerpo de la solicitud enviada a su destino. Para ver un ejemplo, consulte la sección Tipos de autenticación admitidos.
    • Autorización básica: En este caso, client ID y client secret se incluyen en un encabezado Authorization después de ser codificados en Base64 y enviados a su destino. Para ver un ejemplo, consulte la sección Tipos de autenticación admitidos.

Rellenar detalles de destino destination-details

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

Imagen de la pantalla de la interfaz de usuario que muestra los campos completados para los detalles de destino HTTP.

  • Nombre: escriba un nombre para reconocer este destino en el futuro.
  • Descripción: escribe una descripción que te ayudará a identificar este destino en el futuro.
  • Encabezados: escriba los encabezados personalizados que desee incluir en las llamadas de destino, con este formato: header1:value1,header2:value2,...headerN:valueN.
  • Punto final HTTP: Dirección URL del punto final 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. Aplique este formato a los parámetros de consulta que utilice: parameter1=value&parameter2=value.
  • Incluir nombres de segmentos: Cambie la opción si desea que la exportación de datos incluya los nombres de las audiencias que está exportando. Para ver un ejemplo de exportación de datos con esta opción seleccionada, consulte la sección Datos exportados más abajo.
  • Incluir marcas de tiempo de segmentos: actívela si desea que la exportación de datos incluya la marca de tiempo UNIX cuando se crearon y actualizaron las audiencias, así como la marca de tiempo UNIX cuando las audiencias se asignaron al destino para la activación. Para ver un ejemplo de exportación de datos con esta opción seleccionada, consulte la sección Datos exportados más abajo.

Habilitar alertas enable-alerts

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

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

Activar públicos en este destino activate

IMPORTANT

Consulte Activar datos de audiencia en destinos de exportación de perfiles de flujo continuo para obtener instrucciones sobre cómo activar audiencias en este destino.

Atributos de destino attributes

En el paso Seleccionar atributos, Adobe recomienda que seleccione 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 de perfil profile-export-behavior

Experience Platform optimiza el comportamiento de exportación de perfiles a su destino de API HTTP para exportar solo datos a su punto final de API cuando se han producido actualizaciones relevantes en un perfil tras la calificación de la audiencia 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 el abono a audiencia de al menos una de las audiencias asignadas al destino. Por ejemplo, el perfil cumple los requisitos de una de las audiencias asignadas al destino o ha salido de una de las audiencias asignadas al destino.
  • La actualización de perfil se determinó mediante un cambio en el mapa de identidad. Por ejemplo, a un perfil que ya estaba cualificado para una de las audiencias asignadas al destino se le ha añadido una nueva identidad en el atributo del mapa de identidad.
  • La actualización de perfil estaba determinada por 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 una audiencia asignada 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 se encuentren los cambios. Por lo tanto, en el ejemplo anterior, todos los atributos asignados para esos cinco nuevos perfiles se exportarán incluso si los atributos en sí no han cambiado.

Qué determina una exportación de datos y qué se incluye en la exportación what-determines-export-what-is-included

Con respecto a los datos que se exportan para un perfil determinado, es importante entender 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.

Qué determina una exportación de destino
Qué se incluye en la exportación de destino
  • Los atributos y audiencias asignados sirven de referencia para una exportación de destino. Esto significa que si alguna audiencia asignada cambia de estado (de null a realized o de realized a exiting) o si se actualiza algún atributo asignado, se iniciará una exportación de destino.
  • Dado que las identidades no se pueden asignar actualmente a destinos de API HTTP, los cambios en cualquier identidad de un perfil determinado también determinan las exportaciones de destino.
  • Un cambio para un atributo se define como cualquier actualización del atributo, independientemente de si es el mismo valor o no. Esto significa que la sobrescritura de un atributo se considera un cambio aunque el valor en sí no haya cambiado.
  • El objeto segmentMembership incluye la audiencia asignada en el flujo de datos de activación, para la cual el estado del perfil ha cambiado después de un evento de calificación o salida de audiencia. Tenga en cuenta que otras audiencias sin asignar para las que el perfil cumple los requisitos pueden formar parte de la exportación de destino, si estas audiencias pertenecen a la misma política de combinación que la audiencia asignada en el flujo de datos de activación.
  • También se incluyen todas las identidades del objeto identityMap (actualmente, el Experience Platform no admite la asignación de identidades en el destino de la API HTTP).
  • En la exportación de destino solo se incluyen los atributos asignados.

Por ejemplo, considere este flujo de datos para un destino HTTP en el que se seleccionen tres audiencias en el flujo de datos y se asignen cuatro atributos al destino.

Ejemplo de flujo de datos de destino de API HTTP.

Una exportación de perfil al destino puede determinarse mediante un perfil que califique para uno de los tres segmentos asignados o que salga de él. Sin embargo, en la exportación de datos, en el objeto segmentMembership (consulte la sección Datos exportados más abajo), podrían aparecer otras audiencias no asignadas, si ese perfil en particular es miembro de ellas y si comparten la misma política de combinación que la audiencia que activó la exportación. Si un perfil se califica para el segmento Cliente con DeLorean Cars, pero también es miembro de los segmentos de la película Visto "Volver al futuro" y fans de ciencia ficción, entonces estas otras dos audiencias también estarán presentes en el objeto segmentMembership de la exportación de datos, aunque no estén asignadas en el flujo de datos, si comparten la misma política de combinación con el segmento Cliente con DeLorean Cars.

Desde el punto de vista de los atributos de perfil, cualquier cambio en los cuatro atributos asignados anteriormente 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 historical-data-backfill

Cuando se añade una audiencia nueva a un destino existente o se crea un destino nuevo y se le asignan audiencias, Experience Platform exporta al destino los datos históricos de cualificación de audiencias. Los perfiles que cumplen los requisitos para la audiencia antes de que la audiencia se agregó al destino se exportan al destino en un plazo aproximado de una hora.

Datos exportados exported-data

Los datos de Experience Platform exportados llegan a su destino HTTP en formato JSON. Por ejemplo, la exportación siguiente contiene un perfil que se ha clasificado para un segmento determinado, es miembro de otros dos segmentos y ha salido de otro segmento. La exportación también incluye el atributo de perfil nombre, apellidos, fecha de nacimiento y 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":"realized"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"realized"
      },
      "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 las opciones Incluir nombres de segmentos e Incluir marcas de tiempo de segmentos:

La muestra de exportación de datos siguiente incluye nombres de audiencia en la sección segmentMembership
code language-json
"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          }
        }
      }
La muestra de exportación de datos siguiente incluye marcas de tiempo de audiencia en la sección segmentMembership
code language-json
"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

Límites y directiva de reintentos limits-retry-policy

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

En caso de solicitudes fallidas al destino de la API HTTP, el Experience Platform almacena las solicitudes fallidas y las reintenta dos veces para enviar las solicitudes al extremo.

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6