Llamar a una API REST usando el conector HTTP v2 en Jitterbit Studio

Introducción

El conector HTTP v2 establece acceso sobre el protocolo HTTP o HTTPS a servicios como APIs REST, APIs GraphQL y formularios web.

Esta guía cubre dos patrones comunes para trabajar con APIs REST en Studio:

• Usar una actividad HTTP v2 GET como origen para recuperar datos de un endpoint de API REST.
• Usar una actividad HTTP v2 POST como destino para enviar datos a un endpoint de API REST, incluidos webhooks.

Los mismos principios aplican a los tipos de actividad PUT, PATCH y DELETE.

Configurar una conexión HTTP v2

Antes de crear actividades HTTP v2, configura una conexión a la API REST.

1. En Studio, abre un proyecto y haz clic en la pestaña Endpoints y conectores del proyecto en la paleta de componentes de diseño.

2. Haz clic en el conector HTTP v2 para abrir la pantalla de configuración de conexión.

3. Nombre de conexión: Ingresa un nombre único que identifique el servicio de API REST, por ejemplo Customer API. El nombre no debe contener barras diagonales / ni dos puntos :.

4. URL base: Ingresa la URL base de la API, por ejemplo https://api.example.com/v1. Las actividades individuales pueden extender esta URL con un sufijo de ruta u omitirla completamente con una URL completa.

5. Autorización: Usa el menú para seleccionar el tipo de autenticación que requiere la API. Las opciones comunes incluyen:

   • Sin autenticación: Para endpoints públicos que no requieren autenticación.
   • Clave de API: Envía un par clave-valor como encabezado o parámetro de consulta.
   • Token de portador: Envía un token de portador en el encabezado Authorization.
   • Autenticación básica: Envía un nombre de usuario y contraseña codificados en base64 en el encabezado Authorization.

   Para una descripción completa de todos los tipos de autenticación, consulta Tipos de autenticación de conexión HTTP v2.

   Consejo

   Los campos de conexión admiten variables de proyecto. Usa variables de proyecto para credenciales como claves de API, tokens de portador y contraseñas para evitar almacenar valores sensibles directamente en la configuración de conexión.

6. Haz clic en Probar para verificar la conexión. Una prueba es exitosa si la API devuelve cualquier código de estado 2xx (u 405 Método no permitido).

7. Haz clic en Guardar cambios.

Recuperar datos usando una solicitud GET

Una actividad HTTP v2 GET se usa como origen en una operación. Envía una solicitud HTTP GET a la API REST y proporciona la respuesta como entrada al siguiente paso en la operación, típicamente una transformación.

La operación sigue el patrón de transformación:

Crear una actividad GET

En la paleta de componentes de diseño, expande el endpoint HTTP v2 que creaste. Arrastra el tipo de actividad GET al lienzo de diseño para crear una instancia de actividad. Haz doble clic en la actividad para abrir su configuración.

Paso 1: Ingresa un nombre y especifica la configuración

1. Nombre: Ingresa un nombre único para la actividad, por ejemplo Obtener cliente.

2. Ruta: Ingresa la ruta del recurso relativa a la URL base, por ejemplo /customers/{id}. La URL completa en tiempo de ejecución se muestra en el campo URL debajo de Ruta.

   • Si se deja en blanco, se usa la URL base de la conexión en tiempo de ejecución.
   • Una ruta parcial se agrega a la URL base.
   • Una URL completa omite la URL base.

Para incluir un parámetro de ruta, colócalo entre llaves, por ejemplo {id}. Para más información, consulta Usar variables en la ruta de URL a continuación.

1. Parámetros de solicitud: Haz clic en el icono de suma para agregar parámetros de consulta como filas clave-valor, por ejemplo limit / 100. Los parámetros de solicitud se codifican automáticamente en URL.

2. Encabezados de solicitud: Haz clic en el icono de suma para agregar encabezados de solicitud como filas clave-valor, por ejemplo Accept / application/json. Los encabezados definidos aquí se aplican además de cualquier encabezado definido en la conexión.

3. Haz clic en Siguiente.

Pasos 2 y 3: Proporcionar esquemas

El paso 2 permite proporcionar un esquema de solicitud personalizado (opcional para solicitudes GET, que típicamente no tienen cuerpo). El paso 3 permite proporcionar un esquema de respuesta personalizado.

Si la API REST devuelve una estructura JSON conocida, proporciona un esquema JSON personalizado en el paso 3 seleccionando Sí, proporcionar esquema nuevo e introduciendo o pegando el esquema. Esto permite que la transformación asigne campos individuales de la respuesta de la API.

Si no se proporciona un esquema de respuesta personalizado, se utiliza el esquema de respuesta predeterminado del conector. El esquema predeterminado expone el cuerpo de respuesta completo como un único campo responseContent.

Paso 4: Revisar los esquemas de datos

Se muestran los esquemas de solicitud y respuesta configurados. Haz clic en Finalizado para guardar la configuración de la actividad. Los esquemas también están disponibles en cualquier transformación adyacente en el lienzo de diseño.

Acceder a la respuesta en una transformación

En la transformación descendente, asigna campos del esquema de respuesta de la actividad GET al esquema de destino:

• Si se proporcionó un esquema de respuesta personalizado, los campos individuales de la respuesta JSON analizada están disponibles para asignación.
• Si se utiliza el esquema de respuesta predeterminado, el campo responseContent contiene el cuerpo de respuesta sin procesar como una cadena. Utiliza la función JSONParser en un script para analizarlo si es necesario.

Enviar datos mediante una solicitud POST

Una actividad POST de HTTP v2 se utiliza como destino en una operación. Una transformación asigna datos de origen en el cuerpo de la solicitud POST, y la actividad los envía al punto de conexión de la API REST. Este patrón también se aplica al envío de datos a puntos de conexión webhook.

La operación sigue el patrón de transformación:

Crear una actividad POST

En la paleta de componentes de diseño, arrastra el tipo de actividad POST desde el punto de conexión HTTP v2 hacia el lienzo de diseño. Haz doble clic en la actividad para abrir su configuración.

Paso 1: Introducir un nombre y especificar configuraciones

1. Nombre: Introduce un nombre único para la actividad, por ejemplo Crear pedido.

2. Ruta: Introduce la ruta del recurso relativa a la URL base, por ejemplo /orders. Para enviar a un webhook, introduce la URL completa del webhook aquí: una URL completa anula la URL base de la conexión.

3. Encabezados de solicitud: Agrega los encabezados requeridos por la API. Para las API REST que aceptan JSON, agrega Content-Type / application/json.

4. Haz clic en Siguiente.

Pasos 2 y 3: Proporcionar esquemas

El paso 2 (Esquema de solicitud) define la estructura del cuerpo de la solicitud. El paso 3 (Esquema de respuesta) es opcional y captura la respuesta de la API.

Para definir la estructura del cuerpo de la solicitud:

1. En el Paso 2, selecciona Yes, Provide New Schema e ingresa o pega el esquema JSON que coincida con el cuerpo de solicitud esperado por la API. Los campos en este esquema quedan disponibles en la transformación ascendente para mapeo.

2. En el Paso 3, opcionalmente proporciona un esquema de respuesta para capturar campos devueltos por la API, por ejemplo un ID de recurso creado.

3. Haz clic en Finished.

Mapea datos de origen al cuerpo de la solicitud

En la transformación ascendente, mapea campos de origen a los campos definidos en el esquema de solicitud de la actividad POST. La salida de la transformación se convierte en el cuerpo de la solicitud HTTP en tiempo de ejecución.

Usa variables en la ruta URL

Las rutas URL pueden hacerse dinámicas usando tres técnicas:

• Parámetros de ruta son marcadores de posición en el campo Path encerrados entre llaves, por ejemplo /customers/{customerId}. En tiempo de ejecución, el conector sustituye el valor del campo coincidente del esquema de solicitud. En la transformación ascendente, mapea el valor de origen al campo customerId en el esquema de solicitud.

• Variables de proyecto pueden usarse en cualquier lugar donde aparezca un ícono de variable en los campos de conexión o actividad. Escribe un corchete de apertura [ en el campo o haz clic en el ícono de variable para seleccionar una variable de proyecto. Esto es útil para valores específicos del entorno como una URL base que difiere entre desarrollo y producción. Consulta variables de proyecto para más información.

• Variables globales pueden establecerse mediante un script que se ejecuta antes de la operación HTTP v2 en una cadena de operaciones. El script asigna un valor a una variable global (por ejemplo, $gv_customer_id = "12345"), y el campo Path referencia la variable (por ejemplo, /customers/$gv_customer_id). Consulta variables globales para más información.