Filtrar resultados de consultas a la base de datos mediante parámetros de solicitud de API en Jitterbit Studio

Introducción

Cuando se publica una operación como API personalizada, los solicitantes 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 utilizarlos para filtrar resultados en la cláusula WHERE de una actividad Database Query, para luego devolver los registros coincidentes como respuesta de la API.

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

Esta guía asume lo siguiente:

• Se ha configurado una conexión Database y es accesible desde el proyecto.
• La operación se publica como API personalizada con el tipo de respuesta configurado en Variable. Para consultar los pasos de configuración, ver 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 solicitante envía GET /customers?CustomerID=123, entonces $jitterbit.api.request.parameters.CustomerID contiene 123.

Agregar un componente Script como el primer paso de la operación. Este script lee el valor del parámetro, lo almacena en una variable global más corta para su uso 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 juntos protegen contra valores faltantes y vacíos. RaiseError detiene la ejecución inmediatamente y activa la acción de error configurada de la operación.

Reemplazar CustomerID con el nombre del parámetro de URL tal como se documenta para la API. Los nombres de parámetros distinguen entre mayúsculas y minúsculas.

Parte 2: Configurar la actividad Database Query

Agregar una actividad Database Query después del script de validación y configurarla para filtrar registros usando el valor de 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 actividad:

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

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

3. En el campo Value, ingresar 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. Comenzar a escribir un corchete de apertura ([) o hacer clic en el icono para ver las variables disponibles.

4. Hacer clic en Add para añadir la condición a la cláusula WHERE.

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

   Sugerencia

   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. Establecer un valor predeterminado en customer_id en este campo (ver Definir un valor predeterminado) para que Test Query tenga un valor que sustituir, sin necesidad de codificar manualmente 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:

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

Parte 3: Devolver los resultados como respuesta de 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 configurar $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 varios registros, recopila los registros en una matriz en la transformación y serializa la matriz.

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 ver la lista completa de variables disponibles para controlar la respuesta de API, consulta Variables Jitterbit de API.

Verifica la integración

1. Despliega el proyecto.

2. Envía una solicitud de prueba al extremo 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 sin el parámetro:

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

   Confirma que el extremo 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 coincide con ningún registro. Confirma que la respuesta refleja un resultado vacío o un error apropiado, según la forma en que la transformación maneje una consulta de cero registros.

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.