API REST

Creando un conector

Para crear un conector de API REST, siga los pasos que se indican a continuación:

  1. Acceda a la pantalla Connector Manager

  2. Haga clic en + NEW CONNECTOR

  3. Seleccione la tarjeta del conector REST API

  4. Importe un archivo con la especificación Open API 3.0.0

    • En la ventana modal que se abrirá, haga clic en SELECT FILE para encontrar el archivo.

    • Tras localizar el archivo, haga clic en IMPORT.

    • Cuando se importa el archivo, el sistema comprobará si hay errores de estructura y si el archivo está de acuerdo con la versión soportada. Después de la validación, se abrirá la pantalla de configuración del conector, con todos los campos automáticamente llenos con los datos importados.

      Solo está permitido importar archivos con las extensiones json, yaml e yml.

  5. Edite los campos de información del conector (opcional)

    • Name: nombre del conector.

    • Version: versión del conector.

    • Description: descripción del conector.

    • Add icon: añada un icono para representar el conector.

  6. Seleccione las rutas

    • Si quiere, haga clic en Select All para seleccionar todos las rutas disponibles.

      Se puede ver la solicitud (request) y la respuesta (response) de cada ruta seleccionada a la derecha del listado de rutas.

  7. Haga clic en CREATE

create rest api connector

No es posible editar un conector de API REST. Si desea realizar cambios, como seleccionar una nueva ruta, será necesario crear un nuevo conector. Para otras modificaciones, actualice la especificación en el archivo de importación.

Configurando un conector

Para usar el conector que ha creado en el Connector Manager en una integración, usted debe configurarlo en la pantalla Flow. Para ello, siga los pasos que se indican a continuación:

Añada el conector al canvas

  1. Acceda a la pantalla Integration Flows

  2. Seleccione el flujo de integración deseado

    • Si el flujo de integración que va a utilizar el conector ya existe, seleccionelo y abra la pantalla Flow.

    • Si quiere usar el conector en uso nuevo flujo, haga clic en + NEW FLOW.

      Consulte nuestro tutorial sobre cómo crear su primer flujo de integración.

  3. Seleccione el conector en el menú de edición en el canvas

    • Haga clic en el icono icono de conector con signo más del menú de edición de la izquierda.

  4. Busque y seleccione el conector registrado. Puede utilizar la barra de búsqueda search steps icon para encontrarlo.

    • Seleccione el conector en el canvas y haga clic en el icono de edición icono de lápiz para abrir el formulario de configuración.

    • Asegúrese de que el conector esté conectado al step anterior y al step posterior en el canvas.

Cada conector permite solo una conexión de entrada y una conexión de salida.

Al seleccionar el conector en el canvas, podrá:

  • Editarlo ícono de lapiz.

  • Copiarlo ícono de copia. Si el formulario del conector ya está configurado, las configuraciones también se copiarán.

  • Eliminarlo ícono de la papelera.

Rellene el formulario de edición

connector form

  • Name: nombre del conector. Carga automáticamente el nombre que usted utilizó durante la creación del conector, pero puede ser editado.

  • Connector: Campo bloqueado que muestra el nombre del conector en el momento de su creación.

  • Route: seleccione la ruta (ejemplo: GET/customer) que el conector utilizará. Si hay muchas, usted puede escribir el método HTTP o el path para filtrar los resultados.

  • URL: URL que hará la solicitud. Si se ha registrado la URL en las variables de entorno, puede hacer clic en el ícono a la derecha y seleccionarla.

  • Request Timeout: inserte el tiempo límite de la solicitud en milisegundos. Por defecto, el valor es de 3000 milisegundos y el valor máximo es de 300000 milisegundos.

    Haciendo clic en el botón de Properties icono de lista a la derecha de los campos URL y Request Timeout, puede:

    • Filtrar y mostrar variables de entorno y el payload de steps anteriores (si los steps están conectados) para uso en la configuración del formulario.

    • Crear expresiones utilizando el Expression Builder.

  • Security: habilita automáticamente el tipo de seguridad ya configurado en Authorizations. Si hay más de un tipo de seguridad configurado, el campo mostrará un listado con las opciones. Si el conector no tiene ningún tipo de seguridad habilitado, por defecto el campo mostrará la opción No Auth.

  • Ignore Errors: ignora errores durante la ejecución del flujo. Por defecto, este botón está desactivado y puede activarlo.
    Compruebe más detalles sobre su funcionamiento en la tabla abajo:

    Activado switch

    Desactivado switch off

    La ejecución del flujo continúa, incluso si hay errores en el proceso.

    La ejecución se detendrá inmediatamente.

    Los logs muestran el step con un error.

    Los logs muestran la ejecución hasta el step con error.

    Se ejecutarán los steps posteriores.

    No se ejecutará ningún step posterior.

Configure las pestañas: Body, Header, Query y Path

Body

Para configurar el cuerpo de la solicitud, haga clic en + CREATE DATA MAPPING.

Hay dos formas de configuración:

body connector
Data Mapping

El mapeo de datos es fundamental para la integración de diferentes sistemas y aplicaciones, permitiendo el intercambio fluido de información entre ellos. Transforma datos de un formato a otro, ajustando campos y tipos según sea necesario.

Utilizando las columnas "FROM" y "TO", usted puede mapear sus datos manualmente:

  • FROM (DE): indica el origen de los datos, que incluye los steps anteriores y las variables de entorno registradas.

  • TO (PARA): representa el destino de los datos, que corresponde al cuerpo de la solicitud del conector.

data mapping empty

Mapeo de datos de 1 para 1

  1. Seleccione un atributo en la columna "FROM", a la izquierda.

  2. Seleccione un atributo de la columna "TO", a la derecha.

  3. Haga clic en ADD MAPPING.

  4. Haga clic en CONFIRM.

  5. Puede repetir los pasos anteriores tantas veces como sea necesario.

Una vez guardado, será posible visualizar el mapeo de datos en la pestaña Body y la opción de edición estará habilitada.

Vea una demostración en el GIF a continuación:

data mapping 1 to 1

Mapeo de datos de 2 para 1 o más

Para un mapeo de datos de 2 para 1 o más, deberá usar una expresión.

Para ello, antes de seleccionar los atributos en la columna "FROM", haga clic en la función concat (la única función disponible) en la sección EXPRESSION. Si lo prefiere, puede escribir la expresión manualmente.

Solo se puede seleccionar un atributo de la columna "TO", y ese atributo no puede ser elegido más de una vez.

Vea un GIF demostrativo a continuación:

data mapping 2 to 1

Ahora, vea otro ejemplo de mapeo de datos:

  • Uso de la función concat para mapear tres atributos de la columna "FROM" (logradouro, município y UF) para el atributo logradouro de la columna "TO".

  • Mapeo del atributo nome_social de la columna "FROM" para el atributo nome de la columna "TO". El For Each aparece delante de la expresión, ya que es el origen del payload.

  • Mapeo manual de la ciudad "São Paulo" para el atributo cidade de la columna "TO".

Vea estos ejemplos en el GIF a continuación:

data mapping examples

Campos de mapeo de datos

Puede visualizar el mapeo de datos en DATA MAPPING FIELDS.
Cada fila presenta el atributo de entrada (o la expresión) y el atributo de salida en sus respectivas columnas.

Si la flecha entre las columnas "FROM" y "TO" está en gris, esto indica que no hay una expresión asociada. Por otro lado, si la flecha está en naranja, significa que se ha utilizado una expresión.

Para eliminar una fila del mapeo de datos:

  1. Haga clic en la flecha entre las columnas "FROM" y "TO" para seleccionar la fila.

  2. Luego, haga clic en la icono de papelera junto al título de la sección "DATA MAPPING FIELDS".

Estructura de los atributos

Considere el ejemplo de mapeo de datos con la función concat:

concat($.API_Brasil.Response.Payload.logradouro$.API_Brasil.Response.Payload.municipio$.API_Brasil.Response.Payload.uf) ->  $.Request.Payload.endereço.logradouro

Atributos de entrada

Observe cómo las diferentes partes de la estructura de datos de la API aparecen en el mapeo de datos:

  • Response

    • Payload

      • Logradouro

      • Município

      • UF

        concat($.API_Brasil.Response.Payload.logradouro$.API_Brasil.Response.Payload.municipio$.API_Brasil.Response.Payload.uf)

        1. concat: la función concat une los tres elementos en una única string.

        2. $.: convención común en lenguajes de programación y estructuras de datos que utilizan notación de ruta (path notation) para acceder a elementos dentro de objetos o JSON.

        3. API_Brasil.Response.Payload.logradouro: este camino apunta al campo "logradouro" dentro del payload de la respuesta de la API Brasil.

        4. API_Brasil.Response.Payload.município: este camino apunta al campo "município" dentro del payload de la respuesta de la API Brasil.

        5. API_Brasil.Response.Payload.uf: este camino apunta al campo "uf" dentro del payload de la respuesta de la API Brasil.

Atributos de salida

  • Request

    • Payload

      • Endereço

        • Logradouro

          $.Request.Payload.endereço.logradouro

Este fragmento indica que el resultado de la concatenación (la dirección completa) se almacenará en el campo "logradouro" del payload de la solicitud.

Data Mapping con Full Body

En la esquina superior derecha de Data Mapping, puede activar o desactivar el botón FULL BODY.

Así, la solicitud del conector se envía con las propiedades, estructuras y valores de la solicitud de llamada y no tiene que mapearlos uno a uno. Activando el botón, usted automatiza todo el proceso de mapeo de datos.

full body

Para automatizar el proceso, siga estos pasos:

  1. Active FULL BODY.

  2. En el campo Input Data, seleccione el step para aplicar la asignación de datos. Podrá seleccionar el payload de solicitud/respuesta de los conectores, el payload de solicitud del gatillo o el For Each.

  3. En Full Data Mapping, visualice el mapeo realizado automáticamente transformando los campos "FROM" en campos "TO".

  4. Haga clic en CONFIRM para guardar el mapeo de datos.

Una vez guardado, podrá visualizarlo en la pestaña Body y se habilitará la opción de edición.

Haciendo clic en la pestaña Header, se pueden ver los encabezados asociados a la ruta elegida al configurar el formulario del conector de API REST.

Configure los siguientes campos:

  • Name: por defecto, el formulario carga el nombre automáticamente. Si no hay ninguno, puede introducirlo manualmente.

  • Value: inserte el valor del encabezado. Puede hacerlo manualmente o utilizando el botón icono de expression para acceder al Expression Builder. En este caso, puede crear expresiones o simplemente utilizar la columna Properties para seleccionar los atributos y hacer clic en CONFIRM.

header connector

Query

Haciendo clic en la pestaña Query, se pueden ver los parámetros de consulta asociados a la ruta elegida al configurar el formulario del conector de API REST.

Configure los siguientes campos:

  • Name: por defecto, el formulario carga el nombre automáticamente. Si no hay ninguno, puede introducir el nombre manualmente.

  • Value: inserte el valor del parámetro de consulta. Puede hacerlo manualmente o utilizando el botón icono de expression para acceder al Expression Builder. En este caso, puede crear expresiones o simplemente utilizar la columna Properties para seleccionar los atributos y hacer clic en CONFIRM.

query connector

Path

Haciendo clic en la pestaña Path, se pueden ver los parámetros de ruta asociados a la ruta elegida al configurar el formulario del conector de API REST.

Configure los siguientes campos obligatorios:

  • Name: por defecto, el formulario carga el nombre automáticamente. Si no hay ninguno, el campo se bloquea.

  • Value: inserte el valor del parámetro de ruta. Puede hacerlo manualmente o utilizando el botón icono de expression para acceder al Expression Builder. En este caso, puede crear expresiones o simplemente utilizar la columna Properties para seleccionar los atributos y hacer clic en CONFIRM.

path connector

Una vez finalizada la configuración del conector, haga clic en SAVE.

Expression Builder

El componente Expression Builder le permite crear expresiones con parámetros y variables mediante funciones y condiciones disponibles dentro del componente. Así, puede ajustar la expresión según lo requieran sus necesidades.

Puede crear expresiones para los siguientes campos:

  • URL;

  • Request Timeout.

Siga los pasos a continuación para acceder a la pantalla de Expression Builder:

  1. Haga clic en el icono Properties icono de lista, a la derecha de los campos URL o Request Timeout.

  2. A continuación, haga clic en el icono icono de expresion de la esquina superior derecha.

expression builder connector

La pantalla de Expression Builder contiene las siguientes secciones:

  • Properties: muestra los datos de los steps anteriores y de las variables de entorno. Puede filtrar los atributos utilizando el campo de búsqueda situado en la parte superior de la sección y haciendo clic en icono lupa. Puede seleccionar más de un atributo. Al seleccionarlo, el atributo aparece en el campo Expression.

  • Expression: campo para insertar los atributos de entrada o crear una expresión haciendo clic en el botón boton fx a la derecha. Solo la función Concat está disponible para crear la expresión.

Al seleccionar dos o más atributos en el campo Properties, la creación de una expresión será obligatoria.

Para guardar la información, haga clic en CONFIRM y, para salir de la pantalla, y cancelar la operación, haga clic en X, en la esquina superior derecha.

Alerta alertIcon

Un ícono de alerta aparecerá en el conector si:

  • Los campos a continuación no están configurados:

    • Route

    • URL

    • Request Timeout

    • Security

  • Las variables de entorno registradas han sido modificadas o eliminadas.

  • Los atributos definidos en steps anteriores han sido modificados o eliminados mientras todavía se están utilizando en el step configurado.

Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]