API externa external-api
Descripción description
La actividad de External API introduce datos en el flujo de trabajo desde un sistema externo a través de una llamada de API HTTP.
Los extremos externos del sistema pueden ser extremos de API públicos, sistemas de administración de clientes o instancias de aplicaciones sin servidor (por ejemplo, Adobe I/O Runtime), por mencionar algunas categorías.
Las principales características de esta actividad son:
- Capacidad para pasar datos en formato JSON a un extremo de API de REST de terceros.
- Capacidad para recibir una respuesta JSON, asignarla a tablas de salida y pasar a otras actividades de flujo de trabajo.
- Administración de errores con una transición específica de salida.
Avisos de compatibilidad con versiones anteriores from-beta-to-ga
Con la versión Campaign Standard 20.4, se han reducido los márgenes de límite de tamaño de datos de respuesta http y de tiempo de espera de respuesta para ajustarse a las prácticas recomendadas; consulte Limitaciones y protecciones. Estas modificaciones en el mecanismo de protección no tendrán efecto en las actividades de API externas existentes; por lo tanto, se recomienda reemplazar las actividades de API externas existentes con nuevas versiones en todos los flujos de trabajo.
Al reemplazar actividades de API externas, añada la nueva actividad de API externa al flujo de trabajo, copie manualmente los detalles de configuración y, a continuación, elimine la actividad antigua.
Limitaciones y barreras guardrails
Esta actividad se rige por los siguientes mecanismos de protección:
- Límite de tamaño de datos de respuesta http de 5 MB (Nota: Esto supone un cambio con respecto al límite de 50 MB de la versión anterior).
- El tiempo de espera de la solicitud es de 1 minuto (Nota: Esto supone un cambio con respecto al tiempo de espera de 10 minutos de la versión anterior).
- No se permiten redirecciones HTTP.
- Se rechazan las direcciones URL que no son HTTPS.
- Están permitidos el encabezado de solicitud “Accept: application/json” y el encabezado de respuesta “Content-Type: application/json”.
Se han establecido mecanismos de protección específicos:
- Profundidad máxima de JSON: limitar la profundidad máxima de un archivo JSON personalizado anidado que se puede procesar a 10 niveles.
- Longitud máxima de clave JSON: limitar la longitud máxima de la clave interna generada a 255. Esta clave está asociada al ID de columna.
- Se permiten las claves de duplicado máximas de JSON: limitar el número total máximo de nombres de propiedades JSON de duplicado, que se utilizan como ID de columna, a 150.
Configuración configuration
Arrastre y suelte una actividad de External API en el flujo de trabajo y ábrala para comenzar con la configuración.
Asignación de entrada
La asignación de entrada es una tabla temporal generada por una actividad de entrada anterior que se muestra y envía como JSON en la interfaz de usuario.
En función de esta tabla temporal, el usuario puede realizar modificaciones en los datos de entrada.
La lista desplegable Recurso de entrada permite seleccionar la actividad de consulta que crea la tabla temporal.
La casilla de verificación Añadir parámetro de recuento añade un valor de recuento para cada fila proveniente de la tabla temporal. Tenga en cuenta que esta casilla de verificación solo está disponible si la actividad de entrada genera una tabla temporal.
La sección Columnas de entrada permite al usuario añadir cualquier campo de la tabla de transición de entrada. Las columnas seleccionadas son las claves del objeto de datos. El objeto de datos en el archivo JSON es una lista de matriz que contiene datos para las columnas seleccionadas de cada fila de la tabla de transición de entrada.
El cuadro de texto Personalizar parámetro le permite añadir un archivo JSON válido con los datos adicionales que necesita la API externa. Estos datos adicionales se añaden al objeto parámetros en el archivo JSON generado.
Asignación de salida
Esta pestaña le permite definir la estructura JSON de muestra devuelta por la llamada de API.
El analizador JSON está diseñado para admitir tipos de patrones de estructura JSON estándar, con algunas excepciones. Un ejemplo de patrón estándar es:{“data”:[{“key”:“value”}, {“key”:“value”},...]}
La definición JSON de muestra debe tener las siguientes características:
- Los elementos de matriz deben contener propiedades de primer nivel (no se admiten niveles más profundos).
Los nombres de propiedades terminan convirtiéndose en nombres de columna para el esquema de salida de la tabla temporal. - Los elementos JSON que se van a recopilar deben tener 10 niveles o menos de anidación dentro de la respuesta JSON.
- La definición del nombre de columna se basa en el primer elemento de la matriz de “datos”.
La definición de columnas (añadir/quitar) y el valor de tipo de la propiedad se pueden editar en la pestaña Definición de columna.
El comportamiento de la casilla Acoplar:
La casilla Acoplar (sin marcar por defecto) sirve para indicar si desea acoplar el archivo JSON a un mapa de clave/valor o no.
-
Cuando la casilla de verificación está desactivada (sin marcar), el archivo JSON de muestra se analiza para buscar un objeto de matriz. El usuario debe proporcionar una versión recortada como muestra de la respuesta de API en formato JSON para que Adobe Campaign pueda determinar exactamente qué matriz le interesa utilizar. En el momento de la creación del flujo de trabajo, se determina y registra la ruta al objeto de matriz anidado, de modo que se pueda utilizar en el momento de la ejecución para acceder a ese objeto de matriz desde el cuerpo de respuesta JSON recibido de la llamada de API.
-
Cuando la casilla de verificación está activada (marcada), el archivo JSON de muestra se acopla y todas las propiedades especificadas en el archivo de muestra proporcionado se utilizan para crear columnas de la tabla temporal de salida y se muestran en la pestaña Definiciones de columna. Tenga en cuenta que si hay algún objeto de matriz en el archivo JSON de muestra, también se acoplan todos los elementos de esos objetos de matriz.
Si se valida el análisis, aparece un mensaje que le invita a personalizar la asignación de datos en la pestaña “Definición de columna”. En otros casos, se muestra un mensaje de error.
Ejecución
Esta pestaña permite definir el extremo de la conexión. El campo URL le permite definir el extremo HTTPS con el que se comunicará el Campaign Standard.
Si lo necesita el extremo, hay dos tipos de método de autenticación disponibles:
-
Autenticación básica: escriba la información de nombre de usuario y contraseña en la sección Request Header(s).
-
Autenticación OAuth: Al hacer clic en Use connection parameters defined in an external account en una cuenta externa, puede seleccionar una cuenta externa donde se defina la autenticación OAuth. Para obtener más información, consulte la sección Cuentas externas .
Propiedades
Esta pestaña le permite controlar las propiedades generales de la actividad de API externa, como las que se muestran en la interfaz de usuario. El ID interno no se puede personalizar.
Definición de columna
La pestaña Definición de columna le permite especificar con precisión la estructura de datos de cada columna para importar datos que no contengan errores y hacer que coincidan con los tipos que ya están presentes en la base de datos de Adobe Campaign para futuras operaciones.
Por ejemplo, puede cambiar la etiqueta de una columna y seleccionar su tipo (cadena, entero, fecha, etc.) o incluso especificar el procesamiento de errores.
Para obtener más información, consulte la sección Cargar archivo.
Transición
Esta pestaña le permite activar la transición de salida y su etiqueta. Esta transición específica resulta útil en caso de tiempo de espera o si la carga supera el límite de tamaño de datos.
Opciones de ejecución
Esta pestaña está disponible en la mayoría de las actividades de flujo de trabajo. Para obtener más información, consulte la sección Propiedades de actividad.
Pruebas
Para probar la funcionalidad de la API externa con un punto final de prueba simple, puede utilizar Postman Echo: https://docs.postman-echo.com.
Resolución de problemas
Se han añadido dos tipos de mensajes de registro a esta nueva actividad de flujo de trabajo: información y errores. Pueden ayudarle a solucionar problemas potenciales.
Información
Estos mensajes de registro se utilizan para registrar información sobre puntos de comprobación útiles durante la ejecución de la actividad del flujo de trabajo.
Errores
Estos mensajes de registro se utilizan para registrar información sobre las condiciones de error inesperadas, lo que puede provocar que la actividad del flujo de trabajo falle.
No se ha podido analizar la dirección URL de la API (error: “-2010”).
Nota: Este error se registra cuando la dirección URL de la API falla en las reglas de validación.
El host de URL de API no debe ser “localhost” ni literal de dirección IP (host de URL: “localhost”).
El host de URL de API no debe ser “localhost” ni literal de dirección IP (host de URL: “192.168.0.5”).
El host de URL de API no debe ser “localhost” ni literal de dirección IP (host de URL: “[2001]”).
No se ha podido crear el cuerpo de la solicitud JSON. Error al añadir “parámetros”.
No se ha podido crear el cuerpo de la solicitud JSON. Error al añadir “datos”.
HTTP header key is bad (header key: '%s').
Nota: Este error se registra cuando la clave de encabezado personalizada falla en la validación según RFC.
HTTP header value is bad (header value: '%s').
Nota: Este error se registra cuando el valor del encabezado personalizado falla en la validación según RFC.
Formato JSON no correcto o no compatible.
Nota: Este mensaje solo se aplica al análisis del cuerpo de respuesta desde la API externa y se registra al intentar validar si el cuerpo de respuesta se ajusta al formato JSON establecido por esta actividad.
Cuando falla la actividad debido a la respuesta de error HTTP 401: error de actividad (motivo: “HTTP - 401”)
Cuando falla la actividad debido a una llamada interna fallida: error de actividad (motivo: “iRc - -Nn”).
Cuando falla la actividad debido a un encabezado de Content-Type no válido: error de actividad (motivo: “Content-Type - application/html”).