Lidar com paginação ao ler de uma API no Jitterbit Studio

Introdução

A maioria das APIs REST limita o número de registros retornados em uma única resposta. Quando um conjunto de dados é maior que esse limite, a API divide os resultados em várias páginas e espera que o chamador solicite cada página em sequência. Sem suporte a paginação, uma operação do Studio recupera apenas a primeira página e descarta silenciosamente o restante.

Este guia aborda a abordagem de paginação por número de página, onde cada solicitação inclui um parâmetro page que incrementa a cada chamada. Uma nota no final da Parte 2 descreve como adaptar o padrão para APIs baseadas em cursor.

Este guia pressupõe familiaridade com a configuração de conexões e atividades HTTP v2. Para uma introdução geral, consulte Chamar uma API REST usando o conector HTTP v2.

Padrão de design

O padrão usa duas operações:

Operação de busca de página: Lê uma página da API e escreve os registros no destino, usando o padrão de transformação:

flowchart LR A[Atividade HTTP v2 GET] --> B[Transformação] --> C[Atividade de destino]
Operação de controlador: Uma única etapa de script que faz loop até que todas as páginas sejam recuperadas.

O script do controlador usa um loop While que chama RunOperation na operação de busca de página para cada página. RunOperation é executado de forma síncrona por padrão, portanto as alterações de variável global feitas dentro da operação de busca de página (incluindo o sinal de que não há mais páginas) ficam visíveis no controlador após cada chamada.

Duas variáveis globais coordenam o loop:

page: o número da página atual, inicializado como 1 no controlador e incrementado após cada busca.
has_more: um sinalizador inicializado como true e definido como false pela transformação quando a última página é detectada.

Parte 1: Configurar a operação de busca de página

Etapa 1: Configurar a atividade HTTP v2 GET

Na tela de design, arraste uma atividade HTTP v2 GET de um endpoint existente para a tela para iniciar a operação de busca de página.
Clique duas vezes na atividade para abrir sua configuração.
Nome: Digite um nome como Get Contacts Page.
Caminho: Digite o caminho do endpoint da API, por exemplo /contacts.
Parâmetros de Solicitação: Clique no ícone de adição para adicionar uma linha e digite o seguinte:
- Nome: page
- Valor: $page
Isso passa a variável global page como um parâmetro de consulta em cada solicitação. Adicione uma segunda linha com Nome per_page e um valor fixo como 100 para controlar o número de registros retornados por página.
Clique em Próximo.

Etapa 2: Definir o esquema de resposta

Selecione Sim, Fornecer Novo Esquema.

Digite um esquema JSON que inclua a matriz de registros e o campo de metadados de paginação retornado pela API. O esquema de exemplo a seguir representa uma resposta que inclui uma matriz contacts e um 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" }
  }
}

Ajuste o esquema para corresponder à estrutura de resposta real da sua API.

Clique em Próximo e depois em Concluído.

Parte 2: Extrair estado de paginação na transformação

A transformação mapeia os campos de origem da atividade GET para a atividade de destino e usa um script para atualizar a variável global has_more com base em se há mais páginas.

Abra a transformação que segue a atividade GET.
Mapeie cada campo da matriz de origem contacts para os campos de destino correspondentes.
Na transformação, adicione um script no nível raiz (fora do nó de loop) que define has_more com base no valor total_pages da resposta:
```
$total_pages = Source.total_pages;
If($page >= $total_pages, $has_more = false);
```

Isso lê o valor total_pages da resposta e define $has_more = false quando a página atual é a última.

Dica

Se a API não retornar uma contagem total de páginas, mas simplesmente retornar menos registros do que o tamanho da página quando a última página é atingida, use a contagem de registros para detectar o fim:

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

Substitua 100 pelo valor per_page configurado na atividade GET.

Paginação baseada em cursor

Algumas APIs retornam um cursor ou uma URL next_page na resposta em vez de uma contagem total de páginas. Para adaptar esse padrão para APIs baseadas em cursor, substitua page por uma variável global cursor (inicializada como ""), passe cursor como um parâmetro de solicitação chamado cursor e no mapa de transformação mapeie o campo next_cursor da resposta para cursor. Defina has_more = false quando cursor estiver vazio:

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

Remova o incremento $page++ do script do controlador descrito na Parte 3.

Parte 3: Escrever o script do controlador

A operação do controlador contém um único script que inicializa o estado do loop e chama a operação de busca de página repetidamente até que todas as páginas sejam processadas.

Na tela de design, crie uma nova operação contendo apenas uma etapa Script.

Clique duas vezes no script para abrir o editor e digite o seguinte:

$page = 1;
$has_more = true;

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

Substitua Fetch Page pelo nome exato da operação de busca de página.

Salve o script.

Pontos-chave sobre este script:

page e has_more são variáveis globais herdadas pela operação de busca de página em cada chamada síncrona RunOperation.
Após cada página ser processada, o controlador incrementa page antes de iniciar a próxima iteração.
RaiseError(GetLastError()) interrompe o loop imediatamente e expõe a falha se a operação de busca de página retornar um erro.
RunOperation também está sujeito a um limite separado no nível do agente para chamadas síncronas feitas dentro de um único loop While (50 por padrão). Se a API paginar além de 50 páginas, esse loop atinge esse limite antes de has_more ficar false: RunOperation retorna false e RaiseError(GetLastError()) interrompe a operação com a mensagem de erro do limite em vez de concluir a sincronização. Consulte a nota em RunOperation para saber como configurar ou substituir esse limite.
A função While impõe uma contagem máxima de iterações, que é padronizada em 50.000. Para APIs com conjuntos de dados muito grandes, defina $jitterbit.scripting.while.max_iterations para um limite apropriado antes do loop:
```
$jitterbit.scripting.while.max_iterations = 2000;
$page = 1;
$has_more = true;

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

Verificar a integração

Implante e execute a operação do controlador. Verifique os logs de operação: a operação de busca de página aparece uma vez por página, portanto a contagem de entradas de log confirma quantas páginas foram recuperadas. Verifique se a contagem total de registros no destino corresponde ao conjunto de dados completo esperado da API.

Para testar o encerramento antecipado antes de processar um conjunto de dados completo, defina $jitterbit.scripting.while.max_iterations = 3 no script do controlador na primeira execução. Isso limita o loop a três páginas e permite confirmar que o incremento de página, o mapeamento de esquema e a lógica has_more estão funcionando corretamente antes de remover o limite e executar contra o conjunto de dados completo.

Para adicionar novas tentativas automáticas se uma busca de página falhar, consulte Repetir uma operação com falha. Para orientação sobre como construir cadeias de consulta com valores de cursor ou filtro dinâmicos, consulte Criar cadeias de consulta dinâmicas para chamadas de API REST.