Gestionar la paginación al leer desde una API en Jitterbit Studio

Introducción

La mayoría de las API REST limitan la cantidad de registros devueltos en una única respuesta. Cuando un conjunto de datos es mayor que ese límite, la API divide los resultados en múltiples páginas y espera que quien realiza la llamada solicite cada página en secuencia. Sin soporte de paginación, una operación de Studio solo recupera la primera página y descarta silenciosamente el resto.

Esta guía cubre el enfoque de paginación por número de página, donde cada solicitud incluye un parámetro page que se incrementa con cada llamada. Una nota al final de la Parte 2 describe cómo adaptar el patrón para APIs basadas en cursores.

Esta guía asume familiaridad con la configuración de conexiones y actividades HTTP v2. Para una introducción general, consulta Llamar a una API REST usando el conector HTTP v2.

Patrón de diseño

El patrón utiliza dos operaciones:

• Operación Fetch page (Obtener página): Lee una página de la API y escribe los registros en el destino, utilizando el patrón de transformación:

  %%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[Actividad HTTP v2 GET] --> B[Transformación] --> C[Actividad de destino]

• Operación controladora: Un paso de script único que realiza un bucle hasta que se recuperan todas las páginas.

El script controlador utiliza un bucle While que llama a RunOperation en la operación Fetch page para cada página. RunOperation se ejecuta de forma sincrónica por defecto, por lo que los cambios en variables globales realizados dentro de la operación Fetch page (incluida la señal de que no quedan más páginas) son visibles nuevamente en el controlador después de cada llamada.

Dos variables globales coordinan el bucle:

• page: el número de página actual, inicializado a 1 en el controlador e incrementado después de cada obtención.
• has_more: una bandera inicializada a true y establecida a false por la transformación cuando se detecta la última página.

Parte 1: Configurar la operación Fetch page

Paso 1: Configurar la actividad HTTP v2 GET

1. En el lienzo de diseño, arrastra una actividad HTTP v2 GET desde un punto de conexión existente al lienzo para iniciar la operación Fetch page.

2. Haz doble clic en la actividad para abrir su configuración.

3. Nombre: Introduce un nombre como Get Contacts Page.

4. Ruta: Introduce la ruta del punto de conexión de la API, por ejemplo /contacts.

5. Parámetros de solicitud: Haz clic en el icono agregar para añadir una fila e introduce lo siguiente:

   • Nombre: page
   • Valor: $page

   Esto pasa la variable global page como parámetro de consulta en cada solicitud. Añade una segunda fila con Nombre per_page y un valor fijo como 100 para controlar la cantidad de registros devueltos por página.

6. Haz clic en Siguiente.

Paso 2: Definir el esquema de respuesta

1. Selecciona Sí, proporcionar un esquema nuevo.

2. Introduce un esquema JSON que incluya la matriz de registros y el campo de metadatos de paginación devuelto por la API. El siguiente esquema de ejemplo representa una respuesta que incluye una matriz contacts y un campo total_pages:

   {
     "type": "object",
     "properties": {
       "contacts": {
         "type": "array",
         "items": {
           "type": "object",
           "properties": {
             "id": { "type": "string" },
             "name": { "type": "string" },
             "email": { "type": "string" }
           }
         }
       },
       "total_pages": { "type": "integer" }
     }
   }
   

   Ajusta el esquema para que coincida con la estructura de respuesta real de tu API.

3. Haz clic en Siguiente y luego en Finalizado.

Parte 2: Extraer el estado de paginación en la transformación

La transformación mapea los campos de origen de la actividad GET a la actividad de destino y utiliza un script para actualizar la variable global has_more según si quedan más páginas.

1. Abre la transformación que sigue a la actividad GET.

2. Mapea cada campo de la matriz de origen contacts a los campos de destino correspondientes.

3. En la transformación, añade un script a nivel raíz (fuera del nodo de bucle) que establezca has_more según el valor total_pages de la respuesta:

$total_pages = Source.total_pages;
If($page >= $total_pages, $has_more = false);

Esto lee el valor total_pages de la respuesta y establece $has_more = false cuando la página actual es la última.

If(Count(Source.contacts.id) < 100, $has_more = false);

$cursor = Source.next_cursor;
If($cursor == "", $has_more = false);

Parte 3: Escribe el script del controlador

La operación del controlador contiene un único script que inicializa el estado del bucle y llama a la operación de obtención de página repetidamente hasta que se hayan procesado todas las páginas.

1. En el lienzo de diseño, crea una nueva operación que contenga solo un paso Script.

2. Haz doble clic en el script para abrir el editor e ingresa lo siguiente:

   $page = 1;
   $has_more = true;
   
   While($has_more,
       If(!RunOperation("<TAG>operation:Fetch Page</TAG>"), RaiseError(GetLastError()));
       $page++;
   );
   

   Reemplaza Fetch Page con el nombre exacto de la operación de obtención de página.

3. Guarda el script.

Puntos clave sobre este script:

• page y has_more son variables globales heredadas por la operación de obtención de página en cada llamada sincrónica de RunOperation.
• Después de procesar cada página, el controlador incrementa page antes de comenzar la siguiente iteración.
• RaiseError(GetLastError()) detiene el bucle inmediatamente y expone el error si la operación de obtención de página devuelve un error.
• RunOperation también está sujeto a un límite separado a nivel de agente en llamadas sincrónicas realizadas dentro de un único bucle While (50 por defecto). Si la API pagina más allá de 50 páginas, este bucle alcanza ese límite antes de que has_more sea false: RunOperation devuelve false, y RaiseError(GetLastError()) detiene la operación con el mensaje de error del límite en lugar de completar la sincronización. Consulta la nota en RunOperation para saber cómo configurar o anular este límite.

• La función While aplica un recuento máximo de iteraciones, que por defecto es 50,000. Para APIs con conjuntos de datos muy grandes, establece $jitterbit.scripting.while.max_iterations en un límite apropiado antes del bucle:

  $jitterbit.scripting.while.max_iterations = 2000;
  $page = 1;
  $has_more = true;
  
  While($has_more,
      If(!RunOperation("<TAG>operation:Fetch Page</TAG>"), RaiseError(GetLastError()));
      $page++;
  );
  

Verifica la integración

Implementa y ejecuta la operación del controlador. Consulta los registros de operación: la operación de obtención de página aparece una vez por página, por lo que el recuento de entradas de registro confirma cuántas páginas se obtuvieron. Verifica que el recuento total de registros en el destino coincida con el conjunto de datos completo esperado de la API.

Para probar la terminación temprana antes de procesar un conjunto de datos completo, establece $jitterbit.scripting.while.max_iterations = 3 en el script del controlador en la primera ejecución. Esto limita el bucle a tres páginas y te permite confirmar que el incremento de página, el mapeo de esquema y la lógica de has_more funcionan correctamente antes de eliminar el límite y ejecutar contra el conjunto de datos completo.

Para agregar reintentos automáticos si falla la obtención de una página, consulta Reintentar una operación fallida. Para obtener orientación sobre cómo construir cadenas de consulta con valores de cursor o filtro dinámicos, consulta Construir cadenas de consulta dinámicas para llamadas de API REST.