[Ultimate]{class="badge positive"}

Conexión de API HTTP

Información general overview

El destino de la API HTTP es un destino de flujo continuo de Experience Platform que le ayuda a enviar datos de perfil a puntos de conexión HTTP de terceros.

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

Casos de uso use-cases

Utilice el destino de la API HTTP para 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.

Audiencias compatibles por tipo de datos de audiencia:

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.

Requisitos previos prerequisites

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

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

Puede utilizar 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 protocolo de autenticación mutua que garantiza que las partes que comparten información sean quienes dicen ser antes de compartir los datos. mTLS incluye un paso adicional en comparación con TLS estándar, en el que el servidor también solicita y verifica el certificado del cliente, mientras que el cliente verifica el certificado del servidor.

Consideraciones sobre mTLS mtls-considerations

La compatibilidad con mTLS para destinos de API HTTP se aplica solamente al extremo de recepción de datos donde se envían exportaciones de perfil (el campo HTTP Endpoint en detalles de destino).

Configuración de mTLS para la exportación de datos configuring-mtls

Para usar mTLS con destinos de API HTTP, el HTTP Endpoint (extremo de recepción de datos) que configuró en la página detalles de destino debe tener los protocolos TLS deshabilitados y solo mTLS habilitado. 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 utilizar mTLS con el destino de la API HTTP, el extremo del servidor receptor de datos debe ser un extremo de conexión habilitado solo para mTLS.

Recuperar e inspeccionar detalles del certificado certificate

Si desea inspeccionar los detalles del certificado, como el nombre común (CN) y los nombres alternativos del sujeto (SAN), para una validación adicional de terceros, utilice la API para recuperar el certificado y extraer esos campos de la respuesta.

Consulte la documentación de extremo de certificado público para obtener más informació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 que se enviarán a la 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:

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'

Conectar con el destino connect-destination

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 Bearer token para conectarse a su extremo HTTP, ingrese la siguiente información y seleccione Connect to destination:

Sin autenticación no-authentication

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

Cuando selecciona esta opción de autenticación, solo necesita seleccionar Connect to destination y se establece la conexión con el 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 a su extremo HTTP, ingrese la siguiente información y seleccione Connect to destination:

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

Si selecciona el tipo de autenticación OAuth 2 Client Credentials para conectarse a su extremo HTTP, ingrese la siguiente información y seleccione Connect to destination:

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.

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 destino mediante la interfaz de usuario.

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

Activar públicos en este destino activate

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 Select attributes, 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 de un perfil tras la calificación de la audiencia u otros eventos significativos. Los perfiles se exportan al destino en las siguientes situaciones:

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 la audiencia, la exportación a su destino es incremental y solo incluye los cinco perfiles nuevos.

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.

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.

Se activa una exportación de perfiles al destino cuando un perfil cumple los requisitos o sale de una de las tres audiencias asignadas. En la exportación de datos, el objeto segmentMembership (consulte Datos exportados más abajo) también puede incluir audiencias no asignadas, si ese perfil es miembro de ellas y comparten la misma política de combinación que la audiencia que activó la exportación. Por ejemplo, si un perfil cumple los requisitos para la audiencia de Customer with DeLorean Cars, pero también es miembro de la película Ver "Volver al futuro" y de las audiencias de fans de ciencia ficción, esas dos audiencias también aparecen en el objeto segmentMembership, siempre que compartan la misma política de combinación con la audiencia de Customer with 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

Al agregar una audiencia nueva a un destino existente o al crear un destino nuevo y asignarle audiencias, Experience Platform exporta al destino los datos de calificación de audiencias históricas. 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 aterrizan en el destino HTTP en formato JSON. Por ejemplo, la exportación siguiente contiene un perfil que se ha clasificado para una audiencia determinada, es miembro de otras dos audiencias y ha salido de otra audiencia. 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 Include Segment Names y Include Segment Timestamps:

"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"
          },
          "354e086f-2e11-49a2-9e39-e5d9a76be683": {
            "lastQualificationTime": "2020-04-15T02:41:50+0000",
            "status": "realized"
          }
        }
      }

"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

El 95 por ciento de las veces, 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.

Cuando las solicitudes al destino de la API HTTP fallan, Experience Platform las almacena y las reintenta dos veces.

Solución de problemas troubleshooting

Para garantizar una entrega de datos fiable y evitar problemas de tiempo de espera, asegúrese de que el extremo HTTP responda en 2 segundos a las solicitudes de Experience Platform, tal como se especifica en la sección requisitos previos. Las respuestas que tarden más tiempo producirán errores de tiempo de espera.