Fuentes de datos externas external-data-sources
Las fuentes de datos externas 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 registrado una habitación. A diferencia de la fuente de datos integrada de 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:
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
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).
Estos son los pasos principales para crear y configurar una nueva fuente de datos externa:
-
En la lista de orígenes de datos, haga clic en Crear Source de datos para crear un nuevo origen de datos externo.
Se abre el panel de configuración de la fuente de datos en el lado derecho de la pantalla.
-
Escriba un nombre para la fuente de datos.
note note NOTE Solo se permiten caracteres alfanuméricos y guiones bajos. La longitud máxima es de 30 caracteres. -
Añada una descripción a la fuente de datos. Este paso es opcional.
-
Añada la dirección URL del servicio externo. En nuestro ejemplo: https://api.adobeweather.org/weather.
note caution CAUTION Recomendamos encarecidamente utilizar HTTPS por motivos de seguridad. Además, tenga en cuenta que no permitimos el uso de direcciones de Adobe que no están disponibles para el público ni de direcciones IP. 
-
Configure la autenticación según la configuración del servicio externo: Sin autenticación, Básico, Personalizado o Clave de API.
Para el modo de autenticación básico, debe introducir un nombre de usuario y una contraseña.
note note NOTE Cuando se realiza la llamada de autenticación, se agrega la cadena <username>:<password>, codificada en base64, en el encabezado Autenticación.Para obtener más información sobre el modo de autenticación personalizada, vea esta sección. En nuestro ejemplo, elegimos el modo de autenticación de clave de API:
- Tipo: "clave de API"
- Nombre: "appid" (el nombre del parámetro de clave de API)
- Valor: "1234" (el valor de nuestra clave de API)
- Ubicación: "Parámetro de consulta" (la clave de API se encuentra en la dirección URL)
-
Agregue un nuevo grupo de campos para cada conjunto de parámetros de API haciendo clic en Agregar nuevo grupo de campos. El nombre del grupo de campos solo puede contener caracteres alfanuméricos y guiones bajos. La longitud máxima es de 30 caracteres. En nuestro ejemplo, necesitamos crear dos grupos de campos, uno para cada conjunto de parámetros (city y long/lat).
Para el conjunto de parámetros "long/lat", creamos un grupo de campos con la siguiente información:
-
Utilizado en: muestra el número de recorridos que utilizan un grupo de campos. Puede hacer clic en el icono Ver recorridos para mostrar la lista de recorridos usando este grupo de campos.
-
Método: seleccione el POST o el método de GET. En nuestro caso, seleccionamos el método GET.
-
Valores dinámicos: escriba los diferentes parámetros separados por coma, "long,lat" en nuestro ejemplo. Dado que los valores de parámetro dependen del contexto de ejecución, se definirán en los recorridos. Más información
-
Carga de respuesta: haga clic dentro del campo Carga útil y pegue un ejemplo de la carga útil devuelta por la llamada. Para nuestro ejemplo, hemos utilizado una carga útil encontrada en un sitio web de la API meteorológica. Compruebe que los tipos de campo son correctos. Cada vez que se llama a la API, el sistema recupera todos los campos incluidos en el ejemplo de carga útil. Tenga en cuenta que puede hacer clic en Pegar una nueva carga útil si desea cambiar la carga útil que se pasa actualmente.
-
Carga útil enviada: este campo no aparece en nuestro ejemplo. Solo está disponible si selecciona el método POST. Pegue la carga útil que se enviará al sistema de terceros.
En el caso de una llamada de 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:
-
enumera los parámetros que se pasarán en el momento de la llamada en el campo Valores dinámicos (en el ejemplo siguiente: "identificador").
-
Especificarlos también con la misma sintaxis en el cuerpo de la carga útil enviada. Para ello, debe agregar: "param": "nombre del parámetro" (en el ejemplo siguiente: "identificador"). Siga esta sintaxis:
code language-none {"id":{"param":"identifier"}}
Haga clic en Guardar.
La fuente de datos ahora está configurada y lista para utilizarse en sus recorridos, por ejemplo en sus 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
Este modo de autenticación 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.
Al configurar la autenticación personalizada, puede hacer clic en el botón a continuación para comprobar si la carga de autenticación personalizada está configurada correctamente.
Si la prueba se realiza correctamente, el botón se vuelve verde.
Con esta autenticación, la ejecución de la acción es un proceso de dos pasos:
- Llame al extremo para generar el token de acceso.
- Llame a la API de REST mediante la inyección adecuada del token de acceso.
Definición del extremo al que se va a llamar para generar el token de acceso custom-authentication-endpoint
-
extremo: dirección URL que se utilizará para generar el extremo
-
método de la petición HTTP en el extremo (GET o POST)
-
encabezados: pares clave-valor que se insertarán como encabezados en esta llamada, si es necesario
-
cuerpo: describe el cuerpo de la llamada si el método es POST. Apoyamos una estructura de cuerpo limitada, definida en bodyParams (pares clave-valor). bodyType describe el formato y la codificación del cuerpo en la llamada:
- 'form': lo que significa que el tipo de contenido será application/x-www-form-urlencoded (charset UTF-8) y que los pares clave-valor se serializarán tal cual: key1=value1&key2=value2&…
- 'json': lo que significa que el tipo de contenido será application/json (charset UTF-8) y que los pares clave-valor se serializarán como un objeto json tal cual: { "key1": "value1", "key2": "value2", …}
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
-
authorizationType: define cómo se debe insertar el token de acceso generado en la llamada HTTP para la acción. Los valores posibles son:
- bearer: indica que el token de acceso debe inyectarse en el encabezado Autorización, como: Autorización: Bearer <token de acceso>
- header: indica que el token de acceso debe insertarse como encabezado, el nombre del encabezado definido por la propiedad tokenTarget. Por ejemplo, si el tokenTarget es myHeader, el token de acceso se insertará como un encabezado como: myHeader: <token de acceso>
- queryParam: indica que el token de acceso debe insertarse como queryParam, el nombre del parámetro de consulta definido por la propiedad tokenTarget. Por ejemplo, si tokenTarget es myQueryParam, la dirección URL de la llamada de acción será: <url>?myQueryParam=<token de acceso>
-
tokenInResponse: indica cómo extraer el token de acceso de la llamada de autenticación. Esta propiedad puede ser:
- 'response': indica que la respuesta HTTP es el token de acceso
- un selector en un json (suponiendo que la respuesta es un json, no se admiten otros formatos como XML). El formato de este selector es json://<ruta a la propiedad token de acceso>. Por ejemplo, si la respuesta de la llamada es: { "access_token": "theToken", "timestamp": 12323445656 }, tokenInResponse será: json: //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 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:
{
"authentication": {
"type": "customAuthorization",
"authorizationType": "Bearer",
"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"
}
}
}
Este es un ejemplo del tipo de autenticación de encabezado:
{
"type": "customAuthorization",
"authorizationType": "header",
"tokenTarget": "x-auth-token",
"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"
}
}
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
}