Pedido de API
Consulta um programa terceiro pela sua interface web durante a chamada, guarda a resposta em variáveis, e segue pela saída Erro assim que demora ou falha.
Em resumo
| Saídas | OK e Erro |
| Campos | Método, Timeout, URL, Cabeçalhos (1/linha), Corpo (POST/PUT), e uma tabela de extrações Variável e Caminho JSON |
| Métodos | GET, POST, PUT, DELETE |
| Timeout proposto | 2, 3, 5, 8 ou 10 s, 5 s por predefinição |
| Timeout realmente aplicado | 8 segundos no máximo, mesmo que se escolha 10 |
| Espera de estabelecimento da ligação | 2 segundos |
| Redirecionamentos seguidos | 2 |
| Disjuntor | 5 falhas consecutivas no mesmo servidor abrem o circuito durante 30 segundos |
O texto de ajuda mostrado na janela é: «Consulta uma API HTTP e extrai valores JSON para variáveis. Se a API falhar ou exceder o timeout, a saída «Erro» é utilizada. Utilize {{variavel}} no URL, nos cabeçalhos e no corpo.»
Como funciona
O que é uma API
Uma API é a porta de serviço de um programa: um endereço web que outro programa consulta, e que responde não com uma página para ler, mas com um dado estruturado. A maioria responde em JSON, um formato que organiza a informação por nome, à maneira de um formulário: {"cliente": {"nome": "Silva", "estatuto": "premium"}}.
O módulo envia o pedido, lê a resposta e extrai dela o que interessa.
As variáveis no pedido
O URL, os Cabeçalhos e o Corpo aceitam {{variaveis}}, substituídas imediatamente antes do envio. É assim que se consulta o serviço sobre quem liga no momento: https://api.exemplo.com/cliente/{{caller}}.
A extração
A resposta raramente deve ser aproveitada em bloco. A tabela de baixo associa um Caminho JSON a um nome de Variável. O caminho lê-se de fora para dentro, os níveis separados por pontos: cliente.nome vai buscar nome dentro de cliente. Uma lista percorre-se pela sua posição, começando em zero: 0.nome designa o nome do primeiro elemento.
Um caminho deixado vazio traz a resposta inteira: é o que convém quando o serviço responde diretamente um número ou uma palavra, sem estrutura à volta.
Um caminho que não leva a nada dá uma variável vazia, sem erro. A saída OK é utilizada mesmo assim, visto que o serviço respondeu de facto.
Quando a saída Erro é utilizada
- o URL está vazio;
- o serviço não responde dentro do prazo;
- responde um código de erro, ou seja, qualquer código fora da família dos sucessos;
- o disjuntor está aberto.
O disjuntor
Um serviço avariado não deve atrasar todas as chamadas. Depois de 5 falhas consecutivas para o mesmo servidor, o módulo deixa de o chamar durante 30 segundos: a saída Erro é utilizada de imediato, sem esperar o prazo e sem sequer enviar o pedido. Um primeiro sucesso repõe o contador a zero.
É uma proteção, e isso explica uma observação intrigante: durante esses trinta segundos, a chamada segue para Erro num piscar de olhos, mesmo que o serviço já esteja talvez restabelecido.
O que preencher
| Campo | O que é esperado | Se o deixar vazio |
|---|---|---|
| Método | GET para ler, POST ou PUT para enviar, DELETE para eliminar | GET |
| Timeout | o prazo de espera, reduzido a 8 s no máximo na execução | 5 s |
| URL | o endereço completo, que aceita {{variaveis}} | a saída Erro é utilizada sem que nenhum pedido parta |
| Cabeçalhos (1/linha) | um cabeçalho por linha, por exemplo uma chave de autenticação | nenhum cabeçalho é enviado |
| Corpo (POST/PUT) | o conteúdo enviado, em geral JSON | nenhum conteúdo; o corpo é de qualquer forma ignorado em GET |
| Variável de uma extração | o nome sob o qual guardar o valor lido | a linha é ignorada |
| Caminho JSON de uma extração | o caminho até ao valor, por exemplo cliente.nome | a resposta inteira é guardada na variável |
O botão Adicionar uma extração cria uma linha, Eliminar remove a sua, Guardar fecha a janela.
Passo a passo
- Obtenha do fornecedor o endereço a consultar, a forma de autenticação, e um exemplo de resposta. Sem exemplo de resposta, não será possível escrever os caminhos de extração.
- Coloque o módulo Pedido de API e ligue o nó anterior à sua entrada.
- Abra-o, escolha o Método e regule o Timeout o mais curto que o serviço suportar.
- Indique o URL, inserindo as variáveis a partir do painel Variáveis disponíveis.
- Preencha os Cabeçalhos, um por linha, em geral a linha de autenticação fornecida pelo fornecedor.
- Para um POST ou um PUT, indique o Corpo.
- Clique em Adicionar uma extração e associe um Caminho JSON a um nome de Variável, tantas vezes quantos os valores a recuperar.
- Clique em Guardar, depois ligue OK à continuação normal e Erro a um recurso que trate a chamada sem o dado.
- Coloque um módulo Depuração depois da saída OK, com as variáveis extraídas como mensagem, para ler o que foi realmente recebido.
- Clique em Guardar, depois em Aplicar as alterações na faixa superior.
- Ligue para o número, depois abra o Registo de depuração do plano e verifique os valores extraídos.
Se não funcionar
Todas as chamadas seguem para Erro apesar de o URL funcionar num navegador. Um navegador envia os seus cookies de sessão, o módulo não. Verifique o cabeçalho de autenticação. Verifique depois o URL uma vez substituídas as variáveis: um {{nome}} mal escrito passa a vazio e produz um endereço incompleto. Por fim, qualquer resposta fora da família dos sucessos conta como falha, incluindo uma página de erro legível.
A saída Erro é utilizada instantaneamente, sem que o serviço seja chamado. O disjuntor está aberto: cinco falhas consecutivas para esse servidor fizeram-no abrir durante trinta segundos. Espere meio minuto antes de concluir, depois ligue de novo.
Escolhi 10 segundos e a chamada segue ao fim de 8. O prazo está limitado a oito segundos na execução, seja qual for o valor escolhido. É intencional: além disso, quem liga já teria desligado.
A variável extraída está vazia apesar de a resposta conter o dado. O caminho não corresponde. Os níveis separam-se por pontos, as listas contam-se a partir de zero, e um caminho vazio traz a resposta inteira. Extraia primeiro a resposta inteira para uma variável, leia-a no Registo de depuração, depois escreva o caminho exato.
A chamada é cortada quando o serviço não responde. A saída Erro não está ligada a nada. Ligue-a, no mínimo ao atendimento habitual.
Como se constrói o plano de chamadas, explicado em imagens
Ver a página Planos de numeração