Richieste API esterne

Clicca per copiare

Comunicare con qualsiasi API e integrare qualsiasi servizio.


Le richieste API esterne consentono di definire modelli di richiesta e di attivare chiamate in uscita a qualsiasi API dall'interno dei processi aziendali. Con esse è possibile collegare il proprio progetto a qualsiasi servizio di terze parti, anche se non esiste ancora un modulo per esso nel mercato.


Definizione

Consultate le specifiche su come deve essere strutturata la richiesta nella documentazione API del fornitore di servizi con cui volete connettervi.

  1. Per definire un nuovo modello di richiesta, accedere alla scheda "Logica aziendale" nella barra laterale (1), passare alla scheda "Richieste API esterne" (2) e fare clic su "Nuova richiesta API" (3).

2. Assegnare alla nuova richiesta un nome e, facoltativamente, una descrizione.

3. Selezionare il metodo HTTP della richiesta e il suo URL.

4. Definire i parametri dell'URL, i parametri della query (solo per le richieste GET), le intestazioni e il corpo della richiesta inserendo il nome del parametro (1), il suo tipo (2) e facendo clic su "Aggiungi parametro" (3).

Il valore effettivo di questi parametri sarà definito al momento dell'esecuzione del processo aziendale, in cui viene attivata la richiesta.

Per capire la differenza tra parametri URL e parametri di query, leggere qui. Indipendentemente dagli standard, la documentazione API del fornitore di servizi con cui ci si vuole connettere è la migliore fonte di informazioni su come costruire la richiesta.

È anche possibile compilare automaticamente le intestazioni e il corpo della richiesta inserendo un esempio di JSON; il sistema creerà automaticamente tutti i parametri necessari.

Non è necessario aggiungere nuovi parametri a ogni scheda. Alcune richieste possono non contenere alcun parametro URL, intestazione o corpo, ad esempio.

Nel caso in cui la richiesta contenga degli oggetti (ad esempio, auto -> colore, dimensione, ecc.), sarà necessario creare dei modelli virtuali per elaborare questi oggetti successivamente nei processi aziendali. Per farlo, selezionare "Modello" nel selettore del tipo di parametro e introdurre gli elementi figli di cui si ha bisogno. È possibile annidare gli oggetti quante volte si vuole (cioè oggetto nell'oggetto) e creare array di modelli virtuali. Se si è utilizzato il riempimento automatico, questo processo è stato completato automaticamente.

5. Modificare le impostazioni della richiesta, come la verifica SSL, il timeout e la gestione degli errori nella scheda "Impostazioni".

6. Testare la richiesta facendo clic su "Richiesta di prova" e inserendo tutti i parametri richiesti. Controllare la risposta del server e compilare automaticamente le intestazioni e il corpo della risposta, oppure farlo manualmente.

7. Salvare il modello di richiesta facendo clic su "Salva richiesta".

Utilizzo

Dopo aver definito e salvato una nuova richiesta, nell'Editor dei processi aziendali sarà disponibile un nuovo blocco per attivarla.


Si dovranno fornire tutti i componenti che si desidera aggiungere alla richiesta (URL e parametri di query, intestazioni e corpo) come modelli di dati, che possono essere realizzati con questi blocchi. Nell'output, sarà possibile estrarre il corpo formattato della risposta, le intestazioni e lo stato della risposta. È possibile espandere questi modelli utilizzando questi blocchi.

Non è necessario collegare tutti i dati in ingresso perché la richiesta si attivi correttamente. Ad esempio, se si ha una richiesta senza parametri URL, non è necessario creare il suo modello e collegarlo.

Per ogni modello virtuale definito, verranno aggiunti 2 nuovi blocchi all'Editor dei processi aziendali per crearlo ed espanderlo.


Monitoraggio

Ogni volta che si attiva una richiesta API, il sistema invia ai registri il tipo e l'indirizzo, il corpo della richiesta, il codice di stato HTTP della risposta e il corpo della risposta. È possibile inviare ai registri altre informazioni, come campi specifici del corpo della risposta o la latenza, utilizzando il blocco Write to Log.