Visão geral
Uma ferramenta HTTP personalizada deixa o Robô chamar a sua API. Quando essa API devolve listas, ela quase sempre devolve em páginas — e sem configurar isso o Robô lê só a primeira e responde com uma parte dos dados sem saber que faltou o resto.
A Paginação resolve isso. Você diz de que tipo ela é, onde estão os itens na resposta e até quantas páginas percorrer. E, opcionalmente, quantos itens pedir por página.
Pré-requisitos
- Um Robô com pelo menos uma ferramenta HTTP personalizada configurada.
- Saber como a sua API pagina: por número de página ou por cursor.
- Acesso de administrador da conta.
Passo a passo
- Abra Configurações → Robôs e edite o Robô.
- Vá até Ferramentas personalizadas e abra a ferramenta.
- Em Paginação, escolha o tipo: Sem paginação, Número de página ou Cursor.
- Preencha os campos da paginação (veja a tabela abaixo).
- Salve.
Configurações & opções
| Campo | Para que serve |
|---|---|
| Tipo | Sem paginação, Número de página ou Cursor |
| Param de página/cursor | O nome do parâmetro que a API usa para avançar (page, cursor…) |
| Caminho dos itens (array) | Onde, na resposta, está a lista de resultados |
| Caminho do próximo cursor | Onde vem o cursor da próxima página (só no tipo cursor) |
| Página inicial | Por qual página começar |
| Máx. páginas | Teto de páginas a percorrer numa chamada |
| Param do tamanho da página | O nome do parâmetro de tamanho da sua API (per_page, limit…) |
| Itens por página | O valor enviado nesse parâmetro |
Os dois últimos são opcionais e andam juntos: deixar em branco significa não enviar o parâmetro, e aí a API decide o tamanho.
Casos de uso
- API cujo padrão é 100 itens por página: defina
per_page= 20. Cada página vira um pedaço que cabe confortavelmente no contexto, e Máx. páginas controla até onde ir. - API que devolve tudo de uma vez: se ela aceitar um parâmetro de limite, use-o. Uma resposta enorme numa tacada consome o contexto do modelo e sobra pouco para o raciocínio e para a resposta.
- API com cursor: preencha Caminho do próximo cursor; o tamanho da página continua valendo.
Dicas, limites e boas práticas
- Comece com um valor modesto (10 a 25) e suba só se as respostas ficarem incompletas.
- Tamanho de página menor com Máx. páginas maior costuma ser melhor que uma página gigante: o Robô consegue parar quando já achou o que precisava.
- O parâmetro tem que existir na sua API. Um nome que ela não conhece costuma ser ignorado em silêncio — e você fica com a impressão de que a configuração não fez efeito.
- Deixar em branco é uma escolha válida quando o padrão da API já é razoável.
Solução de problemas
O Robô responde com dados parciais. Ou a paginação está em Sem paginação, ou Máx. páginas está baixo demais para o volume que a consulta devolve.
A ferramenta demora muito. Cada página é uma chamada HTTP. Reduza Máx. páginas ou aumente os itens por página para buscar o mesmo volume em menos idas e vindas.
Mudei os itens por página e nada mudou. Confirme o nome do parâmetro com a documentação da sua
API — per_page, limit, page_size e pageSize são todos comuns, e só um deles é o certo.
A lista chega vazia. O Caminho dos itens não está apontando para o array certo na resposta.