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

Introducción

La interfaz de usuario de Parámetros de Solicitud 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 utilizando 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 de status solo cuando un valor de estado está presente).
• Los nombres de los 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 cadenas 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 utilizando concatenación de cadenas

El patrón básico es:

1. Un paso de Script que se ejecuta antes de la actividad GET del 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 fijos 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 declaración 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 o no estar presente, construye una cadena params agregando cada parámetro solo cuando tiene un valor. Usar un prefijo & al inicio de 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 cadena desde el segundo carácter en adelante, eliminando el & inicial dejado por el primer parámetro agregado. La verificación If protege el caso vacío: cuando no se establecen parámetros, query_url es /records sin un ? final.

Sustituir valores usando Replace

Cuando la estructura de la URL es fija y solo cambian valores específicos, una cadena de plantilla con marcadores de posición nombrados 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 ocurrencia coincidente de la cadena 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 un parámetro de ruta HTTP v2).

Codificar valores de parámetros usando URLEncode

Al construir URLs en un 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 en la capa HTTP: el servidor recibe un parámetro truncado o mal formado y típicamente devuelve un error 400 o ningún resultado.
• 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 codifique el nombre del parámetro, solo el valor. Los nombres de los parámetros en las API REST son convencionalmente ASCII y no requieren codificación.

Referenciar la cadena de consulta en una actividad HTTP v2

En el campo Ruta de la actividad GET, ingrese 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 y anula la URL Base de la conexión.
• Un valor que comienza con / se trata como un sufijo de ruta y se agrega a la URL Base.

Utilice un sufijo de ruta (que comience con /) cuando el dominio base y las credenciales de conexión se compartan con otras actividades. Utilice una anulación de URL completa cuando el punto final objetivo esté en un host diferente al de la URL Base, o cuando no se haya establecido ninguna URL Base de conexión.

Verificar la integración

1. Desplegar y ejecutar la operación.

2. Abra el registro de operaciones y confirme que la actividad GET se completó con un código de estado exitoso.

3. Para inspeccionar la URL exacta enviada, agregue una llamada a WriteToOperationLog al final del script de pre-operación:

   WriteToOperationLog("query_url: " & $query_url);
   

   La URL construida aparece en la entrada del registro de operaciones para el paso del script. Elimine la declaración de registro después de confirmar que la URL es correcta.

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