Fuentes de datos externas external-data-sources

En esta página: Conéctese a las API de REST de terceros y configure la autenticación para poder extraer datos externos en sus recorridos para condiciones y personalización.

Trabajo con fuentes de datos externas gs-ext-data-sources

Las fuentes de datos externas le permiten definir una conexión a sistemas de terceros, por ejemplo, si utiliza un sistema de reserva de hoteles para comprobar si la persona ha reservado una habitación. A diferencia de la fuente de datos integrada Adobe Experience Platform, puede crear tantas fuentes de datos externas como necesite.

Las API de REST que utilizan POST o GET y arrojan JSON son compatibles. Se admiten los modos de autenticación básica y personalizada de la clave de API.

Veamos el ejemplo de un servicio de API meteorológica que quiero usar para personalizar el comportamiento de mi recorrido según los datos del tiempo real.

Estos son dos ejemplos de llamada API:

La llamada se compone de una dirección URL principal (https://api.adobeweather.org/weather), dos conjuntos de parámetros (“ciudad” para la ciudad y “lat/long” para la latitud y longitud) y la clave de API (appid).

Creación y configuración de una fuente de datos externa create-ext-data-sources

A continuación se muestran los pasos principales para crear y configurar una nueva fuente de datos externa:

Solo se permiten caracteres alfanuméricos y guiones bajos. La longitud máxima es de 30 caracteres.

Para el conjunto de parámetros “long/lat”, creamos un grupo de campos con la siguiente información:

En el caso de una llamada GET que requiera parámetros, ingrese los parámetros en el campo Valores dinámicos y se agregarán automáticamente al final de la llamada. En caso de una llamada POST, debe hacer esto:

{"id":{"param":"identifier"}}

Una vez guardados los cambios, la fuente de datos está configurada y lista para utilizarse en los recorridos, por ejemplo en las condiciones o para personalizar un correo electrónico. Si la temperatura es superior a 30 °C, puede decidir enviar una comunicación específica.

Modo de autenticación personalizado custom-authentication-mode

El modo de autenticación personalizado se utiliza para la autenticación compleja, utilizada frecuentemente para llamar a protocolos de ajuste de API como OAuth2, para recuperar un token de acceso que se va a insertar en la petición HTTP real de la acción.

Cuando configure la autenticación personalizada, use Haga clic para comprobar el botón de autenticación y controlar si la carga de autenticación personalizada está configurada correctamente.

Cuando la prueba se realiza correctamente, el botón se vuelve verde.

Con este modo de autenticación, la ejecución de la acción es un proceso de dos pasos:

Definición del extremo al que se va a llamar para generar el token de acceso custom-authentication-endpoint

Definición de la forma en que se debe insertar el token de acceso en la petición HTTP de la acción custom-authentication-access-token

El formato de esta autenticación es:

{
    "type": "customAuthorization",
    "endpoint": "<URL of the authentication endpoint>",
    "method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
    (optional) "headers": {
        "<header name>": "<header value>",
        ...
    },
    (optional, mandatory if method is 'POST') "body": {
        "bodyType": "<'form'or 'json'>,
        "bodyParams": {
            "param1": value1,
            ...
        }
    },
    "tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'",
    "cacheDuration": {
        (optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
        (optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
        "timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
    },
    "authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
    (optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
}

Puede cambiar la duración de caché del token para una fuente de datos de autenticación personalizada. A continuación se muestra un ejemplo de una carga útil de autenticación personalizada. La duración de la caché se define en el parámetro cacheDuration. Especifica la duración de retención del token generado en la caché. La unidad puede ser milisegundos, segundos, minutos, horas, días, meses, años.

Este es un ejemplo del tipo de autenticación del portador:

{
    "type": "customAuthorization",
    "endpoint": "https://<your_auth_endpoint>/epsilon/oauth2/access_token",
    "method": "POST",
    "headers": {
      "Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
    },
    "body": {
      "bodyType": "form",
      "bodyParams": {
        "scope": "cn mail givenname uid employeeNumber",
        "grant_type": "password",
        "username": "<epsilon User Name>",
        "password": "<epsilon User Password>"
      }
    },
    "tokenInResponse": "json://access_token",
    "cacheDuration": {
      "duration": 5,
      "timeUnit": "minutes"
    },
  },

Autenticación personalizada basada en certificados certificate-credential

En el caso de las API empresariales que aplican la verificación de identidad basada en certificados (como Microsoft Entra ID), puede configurar la autenticación personalizada basada en certificados agregando "subType": "certificateCredential" a la carga útil de autorización personalizada. Journey Optimizer utiliza el certificado administrado de Adobe para firmar una aserción de cliente JWT e intercambiarla por un token de acceso. No se requiere ningún secreto de cliente.

Esta opción agrega dos campos obligatorios al esquema estándar customAuthorization: subType y aud. Todos los demás campos (endpoint, method, parámetros de cuerpo, tokenInResponse) permanecen sin cambios. Cuando subType está ausente, el comportamiento es idéntico al de la autenticación personalizada estándar: las configuraciones existentes no se ven afectadas.

El usuario nunca crea los campos client_assertion y client_assertion_type. La plataforma los inserta automáticamente durante la ejecución, inmediatamente antes de la llamada del extremo del token.

Funcionamiento certificate-credential-how-it-works

La autenticación personalizada basada en certificados implementa las credenciales del cliente OAuth 2.0 con una aserción de cliente JWT, tal como se define en RFC 7523, el mismo estándar admitido por Microsoft Entra ID y Okta. En lugar de un secreto de cliente, Journey Optimizer prueba su identidad mediante un JWT firmado con la clave privada administrada de Adobe. Su proveedor de identidad verifica la firma utilizando el certificado público de Adobe, que usted registra una vez en su proveedor de identidad.

El intercambio de tokens sigue estos pasos:

Detalles del certificado de Adobe certificate-credential-details

Adobe administra el certificado y su clave privada asociada. La siguiente tabla resume sus propiedades clave:

Adobe gira automáticamente el certificado 60 días antes de la caducidad. El certificado anterior sigue siendo válido hasta 30 días antes de su expiración. Actualmente no se notifica a los clientes. Consulte la protección Rotación de certificados para obtener información sobre cómo supervisar la rotación mediante programación.

Estructura de afirmación de JWT certificate-credential-jwt

No es el autor de la afirmación del cliente JWT: Journey Optimizer la genera y la firma. La estructura esperada se proporciona aquí para que el equipo del proveedor de identidad pueda validar las notificaciones.

Encabezado:

{
  "alg": "RS256",
  "x5t": "<base64url SHA-1 thumbprint of Adobe's leaf certificate>"
}

Carga útil:

{
  "iss": "<client_id>",
  "sub": "<client_id>",
  "aud": "<token endpoint URL>",
  "iat": "<current unix timestamp>",
  "exp": "<iat + 600 seconds>",
  "jti": "<unique UUID per request>"
}

Tenga en cuenta lo siguiente:

Este es un ejemplo del tipo de autenticación de credencial de certificado, para Microsoft Entra ID:

{
  "type": "customAuthorization",
  "subType": "certificateCredential",
  "aud": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
  "authorizationType": "Bearer",
  "endpoint": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
  "method": "POST",
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "client_id": "<your-client-id>",
      "grant_type": "client_credentials",
      "scope": "https://api.example.com/.default"
    }
  },
  "tokenInResponse": "json://access_token"
}

Este es un ejemplo para el mismo tipo de autenticación de credencial de certificado, para Okta:

{
  "type": "customAuthorization",
  "subType": "certificateCredential",
  "authorizationType": "bearer",
  "endpoint": "https://<your-okta-domain>/oauth2/v1/token",
  "aud": "https://<your-okta-domain>/oauth2/v1/token",
  "method": "POST",
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "client_id": "<your-okta-app-client-id>",
      "grant_type": "client_credentials",
      "scope": "<your-api-scope>"
    }
  },
  "tokenInResponse": "json://access_token"
}

Este es un ejemplo del tipo de autenticación de encabezado:

{
  "type": "customAuthorization",
  "endpoint": "https://myapidomain.com/v2/user/login",
  "method": "POST",
  "headers": {
    "x-retailer": "any value"
  },
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "secret": "any value",
      "username": "any value"
    }
  },
  "tokenInResponse": "json://token",
  "cacheDuration": {
    "expiryInResponse": "json://expiryDuration",
    "timeUnit": "minutes"
  },
  "authorizationType": "header",
  "tokenTarget": "x-auth-token"
}

A continuación, se muestra un ejemplo de la respuesta de la llamada de API de inicio de sesión:

{
  "token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
  "expiryDuration" : 5
}