Crear cadenas de consulta dinámicas para llamadas a API REST en Jitterbit Studio

Introducción

La interfaz de usuario Request Parameters del conector HTTP v2 maneja el caso más común: un conjunto fijo de nombres de parámetros cuyos valores cambian en tiempo de ejecución. El conector codifica automáticamente los valores en URL. Para una introducción a este enfoque, consulta Llamar a una API REST usando el conector HTTP v2.

La construcción de cadenas de consulta basada en scripts es necesaria cuando:

• Los parámetros se incluyen o excluyen condicionalmente según los datos de origen (por ejemplo, agregar un filtro status solo cuando hay un valor de estado).
• Los nombres de parámetros varían en tiempo de ejecución (por ejemplo, filter[contact_type] para un tipo de registro y filter[account_type] para otro).
• La URL completa se ensambla a partir de múltiples partes impulsadas por datos.

Esta guía cubre tres técnicas para construir cadenas de consulta en script: concatenación de strings para conjuntos de parámetros condicionales, Replace para sustitución de plantillas fijas, y URLEncode para codificar valores que contienen caracteres especiales.

Construir una cadena de consulta usando concatenación de strings

El patrón básico es:

1. Un paso Script que se ejecuta antes de la actividad GET de HTTP v2 construye la URL y la asigna a una variable global.
2. El campo Path de la actividad GET hace referencia a esa variable global.

La estructura de la operación es:

Estructura de parámetros fija con nombres dinámicos

Cuando el conjunto de parámetros depende de una condición en tiempo de ejecución (como un tipo de registro que determina qué filtros se aplican), utiliza una sentencia If para construir la URL apropiada para cada caso:

// Record type determines which filter parameters apply
If($record_type == "contact",
    $query_url = "/records?type=contact&owner=" & URLEncode($owner_email),
    // Else: account record
    $query_url = "/records?type=account&region=" & URLEncode($region)
);

Parámetros opcionales

Cuando cualquier combinación de parámetros puede estar o no presente, construye una string params añadiendo cada parámetro solo cuando tiene un valor. Usar un prefijo & inicial en cada parámetro evita un separador final:

$params = "";
If($start_date != "",
    $params = $params & "&created_after=" & URLEncode($start_date)
);
If($status != "",
    $params = $params & "&status=" & URLEncode($status)
);
If($owner_email != "",
    $params = $params & "&owner=" & URLEncode($owner_email)
);

// Append the query string only when at least one parameter was set.
// Mid(string, 2) strips the leading & from the first parameter.
If($params != "",
    $query_url = "/records?" & Mid($params, 2),
    $query_url = "/records"
);

Mid con una posición de inicio de 2 devuelve la string desde el segundo carácter en adelante, eliminando el & inicial dejado por el primer parámetro añadido. La verificación If protege el caso vacío: cuando no se establece ningún parámetro, query_url es /records sin ? final.

Sustituir valores usando Replace

Cuando la estructura de la URL es fija y solo cambian valores específicos, una string de plantilla con marcadores de posición con nombre puede ser más limpia que la concatenación. Define la cadena de consulta completa una vez, luego llama a Replace una vez por marcador de posición:

$template = "/contacts?status={status}&created_after={date}&owner={owner}";
$query_url = Replace($template, "{status}", URLEncode($filter_status));
$query_url = Replace($query_url, "{date}",  URLEncode($filter_date));
$query_url = Replace($query_url, "{owner}", URLEncode($owner_email));

Replace sustituye la primera aparición coincidente de la string de búsqueda. Reasigna query_url en cada llamada para encadenar las sustituciones. Elige nombres de marcadores de posición que no aparezcan en otro lugar de la URL (por ejemplo, evita {id} si la ruta ya contiene {id} como parámetro de ruta HTTP v2).

Codificar valores de parámetros usando URLEncode

Cuando construyes URLs en script, llama a URLEncode en cada valor de parámetro. Sin codificación, los valores que contienen caracteres reservados rompen silenciosamente la solicitud:

• Un carácter de espacio divide la URL a nivel HTTP: el servidor recibe un parámetro truncado o malformado y normalmente devuelve un error 400 o sin resultados.
• Un & dentro de un valor se interpreta como un separador de parámetros, dividiendo el valor en dos parámetros separados.
• Otros caracteres que requieren codificación incluyen #, %, =, +, y ?.

La siguiente tabla muestra ejemplos comunes:

No codificar el nombre del parámetro, solo el valor. Por convención, los nombres de parámetros en las API REST son ASCII y no requieren codificación.

Hacer referencia a la cadena de consulta en una actividad HTTP v2

En el campo Ruta de la actividad GET, ingresar la variable global que contiene la URL construida (por ejemplo, query_url).

El campo Ruta sigue estas reglas:

• Un valor que comienza con https:// o http:// se trata como una URL completa e invalida la URL base de la conexión.
• Un valor que comienza con / se trata como un sufijo de ruta y se añade a la URL base.

Utilizar un sufijo de ruta (que comience con /) cuando el dominio base y las credenciales de conexión se comparten con otras actividades. Utilizar un override de URL completa cuando el endpoint de destino se encuentra en un host diferente al de la URL base, o cuando no se establece una URL base de conexión.

Verificar la integración

1. Desplegar y ejecutar la operación.

2. Abrir el registro de operación y confirmar que la actividad GET se completó con un código de estado satisfactorio.

3. Para inspeccionar la URL exacta que se envió, añadir una llamada WriteToOperationLog al final del script anterior a la operación:

   WriteToOperationLog("query_url: " & $query_url);
   

   La URL construida aparece en la entrada del registro de operación del paso del script. Eliminar la instrucción de registro después de confirmar que la URL es correcta.

4. Si la API devuelve resultados inesperados o un error 400, confirmar que URLEncode se aplique a todos los valores que puedan contener espacios o caracteres especiales. Una llamada URLEncode faltante en un valor que contiene & o = es una fuente común de fallos silenciosos.