Richiesta API
Interroga un software terzo tramite la sua interfaccia web durante la chiamata, mette la risposta in variabili, e prende l'uscita Errore non appena la cosa tarda o fallisce.
In breve
| Uscite | OK e Errore |
| Campi | Metodo, Timeout, URL, Intestazioni (1/riga), Corpo (POST/PUT), e un elenco di estrazioni Variabile e Percorso JSON |
| Metodi | GET, POST, PUT, DELETE |
| Timeout proposto | 2, 3, 5, 8 o 10 s, 5 s di default |
| Timeout realmente applicato | 8 secondi al massimo, anche se scegliete 10 |
| Attesa di stabilimento della connessione | 2 secondi |
| Reindirizzamenti seguiti | 2 |
| Interruttore | 5 fallimenti consecutivi sullo stesso server aprono il circuito per 30 secondi |
Il testo di aiuto mostrato nella finestra è: « Interroga un'API HTTP ed estrae valori JSON in variabili. Se l'API fallisce o supera il timeout, viene presa l'uscita « Errore ». Usate {{variable}} nell'URL, nelle intestazioni e nel corpo. »
Come funziona
Cos'è un'API
Un'API è la porta di servizio di un software: un indirizzo web che un altro programma interroga, e che risponde non con una pagina da leggere, ma con un dato strutturato. La maggior parte risponde in JSON, un formato che organizza le informazioni per nome, come un modulo: {"cliente": {"nome": "Rossi", "stato": "premium"}}.
Il modulo invia la richiesta, legge la risposta e ne estrae ciò che vi interessa.
Le variabili nella richiesta
L'URL, le Intestazioni e il Corpo accettano {{variable}}, sostituite subito prima dell'invio. È così che si interroga il servizio sul chiamante in corso: https://api.esempio.com/cliente/{{caller}}.
L'estrazione
La risposta va raramente presa in blocco. La tabella in basso associa un Percorso JSON a un nome di Variabile. Il percorso si legge dall'esterno verso l'interno, i livelli separati da punti: cliente.nome va a cercare nome dentro cliente. Una lista si percorre secondo il suo rango, iniziando da zero: 0.nome indica il nome del primo elemento.
Un percorso lasciato vuoto riporta la risposta intera: è ciò che serve quando il servizio risponde direttamente con un numero o una parola, senza struttura intorno.
Un percorso che non porta a nulla dà una variabile vuota, senza errore. L'uscita OK viene comunque presa, poiché il servizio ha effettivamente risposto.
Quando viene presa l'uscita Errore
- l'URL è vuoto;
- il servizio non risponde entro il tempo previsto;
- risponde con un codice di errore, cioè qualsiasi codice al di fuori della famiglia dei successi;
- l'interruttore è aperto.
L'interruttore
Un servizio in panne non deve rallentare tutte le vostre chiamate. Dopo 5 fallimenti consecutivi verso uno stesso server, il modulo smette di chiamarlo per 30 secondi: l'uscita Errore viene presa immediatamente, senza attendere il tempo previsto e senza nemmeno inviare la richiesta. Un primo successo azzera il contatore.
È una protezione, e ciò spiega un'osservazione sconcertante: durante questi trenta secondi, la chiamata torna in Errore in un lampo, mentre il servizio è forse già ristabilito.
Cosa inserire
| Campo | Cosa è previsto | Se lo lasciate vuoto |
|---|---|---|
| Metodo | GET per leggere, POST o PUT per inviare, DELETE per eliminare | GET |
| Timeout | il tempo di attesa, ridotto a 8 s al massimo in esecuzione | 5 s |
| URL | l'indirizzo completo, che accetta {{variable}} | l'uscita Errore viene presa senza che parta alcuna richiesta |
| Intestazioni (1/riga) | un'intestazione per riga, ad esempio una chiave di autenticazione | nessuna intestazione viene inviata |
| Corpo (POST/PUT) | il contenuto inviato, in genere JSON | nessun contenuto; il corpo viene comunque ignorato in GET |
| Variabile di un'estrazione | il nome sotto cui mettere il valore letto | la riga viene ignorata |
| Percorso JSON di un'estrazione | il percorso verso il valore, ad esempio cliente.nome | la risposta intera viene messa nella variabile |
Il pulsante Aggiungi un'estrazione crea una riga, Elimina rimuove la propria, Salva chiude la finestra.
Procedura
- Ottenete dal vostro fornitore l'indirizzo da interrogare, il modo di autenticarsi, e un esempio di risposta. Senza esempio di risposta, non potrete scrivere i percorsi di estrazione.
- Posizionate il modulo Richiesta API e collegate il nodo precedente al suo ingresso.
- Apritelo, scegliete il Metodo e impostate il Timeout al più breve che il vostro servizio supporta.
- Inserite l'URL, inserendo le variabili dal pannello Variabili disponibili.
- Compilate le Intestazioni, una per riga, in genere la riga di autenticazione fornita dal fornitore.
- Per un POST o un PUT, inserite il Corpo.
- Cliccate su Aggiungi un'estrazione e associate un Percorso JSON a un nome di Variabile, tante volte quanti sono i valori da recuperare.
- Cliccate su Salva, poi collegate OK al seguito normale ed Errore a un ripiego che gestisce la chiamata senza il dato.
- Posizionate un modulo Debug dopo l'uscita OK, con come messaggio le variabili estratte, per leggere ciò che è stato realmente ricevuto.
- Cliccate su Salva, poi su Applica le modifiche nella barra superiore.
- Chiamate il vostro numero, poi aprite il Registro di debug del piano e verificate i valori estratti.
Se non funziona
Tutte le chiamate finiscono in Errore mentre l'URL funziona in un browser. Un browser invia i vostri cookie di sessione, il modulo no. Verificate l'intestazione di autenticazione. Verificate poi l'URL una volta sostituite le variabili: un {{nome}} scritto male diventa vuoto e produce un indirizzo incompleto. Infine, qualsiasi risposta al di fuori della famiglia dei successi conta come un fallimento, compresa una pagina di errore leggibile.
L'uscita Errore viene presa istantaneamente, senza che il servizio venga chiamato. L'interruttore è aperto: cinque fallimenti consecutivi verso questo server lo hanno fatto scattare per trenta secondi. Aspettate mezzo minuto prima di concludere, poi richiamate.
Ho scelto 10 secondi e la chiamata riparte dopo 8. Il tempo è limitato a otto secondi in esecuzione, qualunque sia il valore scelto. È voluto: oltre, il chiamante ha già riagganciato.
La variabile estratta è vuota mentre la risposta contiene il dato. Il percorso non corrisponde. I livelli si separano con punti, le liste si contano a partire da zero, e un percorso vuoto riporta la risposta intera. Estraete prima la risposta intera in una variabile, leggetela nel Registro di debug, poi scrivete il percorso esatto.
La chiamata si interrompe quando il servizio non risponde. L'uscita Errore non è collegata a nulla. Collegatela, come minimo verso l'accoglienza abituale.
Come si costruisce il piano di chiamata, spiegato con le immagini
Vedi la pagina Piani di numerazione