Filtrar resultados de consultas de base de datos usando parámetros de solicitud de API en Jitterbit Studio

Introducción

Cuando se publica una operación como API personalizada, los llamadores pueden pasar valores a través de la URL como parámetros de consulta. Esta guía muestra cómo leer esos valores usando variables API Jitterbit y usarlos para filtrar resultados en la cláusula WHERE de una actividad Database Query, luego devolver los registros coincidentes como respuesta de la API.

Este patrón es útil para construir endpoints de consulta de datos donde el llamador controla qué registros se devuelven: por ejemplo, un endpoint GET que busca un cliente por ID, recupera pedidos para un rango de fechas específico, o devuelve productos filtrados por categoría.

Esta guía asume lo siguiente:

• Una conexión de base de datos está configurada y es accesible desde el proyecto.
• La operación se publica como API personalizada con el tipo de respuesta establecido en Variable. Para los pasos de configuración, consulta Exponer una operación de Studio como API REST.

Patrón de diseño

Parte 1: Agregar un script de validación de parámetros

Los parámetros de URL enviados a la API están disponibles como variables Jitterbit en el formato $jitterbit.api.request.parameters.<name>, donde <name> coincide con la clave del parámetro en la URL. Por ejemplo, si un llamador envía GET /customers?CustomerID=123, entonces $jitterbit.api.request.parameters.CustomerID contiene 123.

Agrega un componente Script como primer paso de la operación. Este script lee el valor del parámetro, lo almacena en una variable global más corta para usar en la consulta, y devuelve un error 400 si el parámetro falta o está vacío:

<trans>
$customer_id = $jitterbit.api.request.parameters.CustomerID;

If(IsNull($customer_id) || Length($customer_id) == 0,
  $err = Dict();
  $err["error"] = "Missing required parameter: CustomerID";
  $jitterbit.api.response = JSONStringify($err);
  $jitterbit.api.response.status_code = 400;
  RaiseError("Missing required parameter");
);
</trans>

IsNull y Length juntas protegen contra un valor faltante y uno vacío. RaiseError detiene la ejecución inmediatamente y activa la acción de error configurada de la operación.

Reemplaza CustomerID con el nombre del parámetro de URL según se documenta para tu API. Los nombres de parámetros distinguen entre mayúsculas y minúsculas.

Parte 2: Configurar la actividad Database Query

Agrega una actividad Database Query después del script de validación y configúrala para filtrar registros usando el valor del parámetro capturado. La variable customer_id establecida por el script de validación está disponible para la actividad en tiempo de ejecución.

Usando el asistente

En Paso 2: Agregar condiciones de la configuración de la actividad:

1. En Select Fields, selecciona los campos a devolver (por ejemplo, CustomerID, Name, y Email).

2. En WHERE clause, usa los menús desplegables para seleccionar el campo y el operador de la condición de filtro.

3. En el campo Value, ingresa la variable usando la sintaxis de corchetes:

   [customer_id]
   

   El icono de variable en el campo indica que se aceptan variables globales, variables de proyecto y variables Jitterbit. Comienza a escribir un corchete de apertura ([) o haz clic en el icono para ver las variables disponibles.

4. Haz clic en Add para agregar la condición a la cláusula WHERE.

5. Haz clic en Test Query para validar la consulta contra la base de datos.

   Consejo

   Debido a que customer_id es una variable global establecida solo en tiempo de ejecución, Test Query fallará si no hay un valor presente. Establece un valor predeterminado en customer_id en este campo (consulta Definir un valor predeterminado) para que Test Query tenga un valor que sustituir, sin necesidad de codificar y eliminar un valor de muestra en el script de validación.

6. Haz clic en Next, revisa el esquema de datos y haz clic en FINISHED.

Uso de SQL manual

Para conexiones JDBC, haz clic en Skip Wizard / Write SQL Statement en el primer paso e ingresa la consulta directamente. Las variables entre corchetes se sustituyen con sus valores en tiempo de ejecución antes de que se ejecute la consulta:

SELECT CustomerID, Name, Email
FROM Customers
WHERE CustomerID = '[customer_id]'

Para columnas numéricas, omite las comillas circundantes:

SELECT OrderID, Total, Status
FROM Orders
WHERE CustomerID = [customer_id]

Parte 3: Devuelve los resultados como respuesta de la API

Agrega una Transformation después de la actividad Query de la base de datos para asignar los campos de resultado a variables de salida. Después de la transformación, agrega un componente Script al final para serializar los resultados y establecer $jitterbit.api.response:

<trans>
$result = Dict();
$result["CustomerID"] = $out_CustomerID;
$result["Name"] = $out_Name;
$result["Email"] = $out_Email;
$jitterbit.api.response = JSONStringify($result);
$jitterbit.api.response.status_code = 200;
</trans>

Reemplaza $out_CustomerID, $out_Name y $out_Email con las variables globales a las que la transformación asigna los campos de resultado de la consulta. Para consultas que pueden devolver múltiples registros, recopílalos en un arreglo en la transformación y serializa el arreglo.

Si $jitterbit.api.response no se establece antes de que se complete la operación, API Manager devuelve una respuesta vacía 200 OK. Para obtener la lista completa de variables disponibles para controlar la respuesta de la API, consulta Variables de Jitterbit de API.

Verifica la integración

1. Implementa el proyecto.

2. Envía una solicitud de prueba al punto de conexión publicado con un valor de parámetro válido:

   GET https://<host>/<service-root>/<version>/<path>?CustomerID=123
   

   Confirma que el cuerpo de la respuesta contiene el registro esperado.

3. Envía una solicitud con el parámetro omitido:

   GET https://<host>/<service-root>/<version>/<path>
   

   Confirma que el punto de conexión devuelve una respuesta 400 con el mensaje de error del script de validación.

4. Envía una solicitud con un valor de parámetro que no coincida con ningún registro. Confirma que la respuesta refleja un resultado vacío o un error apropiado, según cómo la transformación maneje una consulta sin filas.

5. Si algún paso devuelve un resultado inesperado, abre los registros de operación en Studio y los registros de API en API Manager para diagnosticar el problema.