Come creare e configurare una funzione connettore HTTP

Imparare a navigare nella modale della funzione Connector e nel processo di creazione.

Panoramica

Le funzioni connettore sono una funzione per strutturare il modo in cui le applicazioni Tulip interagiscono con i server e i servizi esterni. Se un connettore è la connessione generale tra Tulip e il server esterno, le funzioni connettore sono richieste specifiche di servizi o informazioni. In questo articolo vi spiegheremo come creare e configurare una funzione connettore per accedere a dati o informazioni specifiche da un servizio esterno.

Per informazioni sulle basi delle API, consultate questo articolo su Come usare un'API.

Configurazione

Prima di creare una funzione connettore, è necessario creare un connettore HTTP per creare una connessione tra le applicazioni e il servizio con cui si desidera comunicare. Le funzioni del connettore verranno create all'interno di questo connettore e ogni funzione del connettore all'interno di un connettore condividerà la configurazione del connettore padre. Per creare un connettore HTTP, seguire i passi di questo articolo: Come configurare un connettore.

Una volta creato un connettore, è il momento di creare le funzioni del connettore. Le funzioni del connettore sono le singole operazioni che il connettore esegue per prelevare i dati dal server API a cui ci si collega.

Creare una funzione del connettore

Dalla pagina Connettori, selezionare il connettore con cui si vuole lavorare facendo clic sul suo nome.

Questa pagina mostra un elenco di funzioni associate al connettore. Per creare una nuova funzione del connettore, fare clic su + Crea funzione.

Per essere brevi, in questo articolo daremo per scontato che si conoscano già le diverse parti dell'editor di funzioni del connettore.

Ecco la procedura da seguire per impostare una funzione connettore:

1. Selezionare il tipo API Call.
2. Scrivere l'URL dell'API
3. Impostare gli ingressi
4. Definire i parametri per i dati restituiti
5. Impostare le uscite usando la notazione a punti

Tipo di chiamata e URL

I primi due elementi da configurare per qualsiasi funzione del connettore HTTP sono il tipo di chiamata API (GET, POST, PUT, ecc.) e l'URL dell'endpoint. Selezionare dall'elenco dei tipi di chiamata utilizzando il menu a tendina e inserire il percorso dell'endpoint nel campo successivo all'URL di base. Per un elenco di dettagli sugli endpoint e sulla configurazione, consultare la documentazione dell'API del servizio a cui ci si vuole connettere.

:::(Info) (NOTA) In questo articolo utilizzeremo un gergo: chiamata API. Una chiamata API, o richiesta API, è un messaggio inviato a un server che chiede a un'API di fornire un servizio o un'informazione. Poiché le API sono un modo per far interagire un programma con un altro, le chiamate sono il processo con cui un'applicazione invia una richiesta a un'altra applicazione:

In questo articolo, utilizzeremo come esempio l'API Document360, che è il servizio che ospita la Knowledge Base di Tulip. La funzione che stiamo impostando restituisce un articolo insieme alle proprietà associate in base all'ID dell'articolo.

Diamo un nome alla nostra funzione, impostiamo il tipo di chiamata (GET) e digitiamo l'URL per la chiamata:

:::(Info) (NOTA) L'URL della chiamata è sensibile alle maiuscole e alle minuscole. Assicuratevi di digitarlo esattamente come lo vedete elencato nella documentazione dell'API. :::

Ottenere il tipo di chiamata e l'URL dalla documentazione dell'endpoint del sistema. Queste due azioni determinano la richiesta REST. Per una descrizione dettagliata di cosa sia una richiesta REST, vedere Anatomia di una richiesta REST.

Facendo clic su Test, si esegue la funzione e si ottengono informazioni nella sezione Risultati del test dell'editor. Selezionando Body sotto Test Results, si può visualizzare il risultato completo e non filtrato della richiesta. Bene, abbiamo i dati!

Inputs

Per come è configurata attualmente la nostra funzione connettore, possiamo ottenere solo un ID articolo specifico.

Il nostro obiettivo con questa funzione è di configurarla in modo che restituisca informazioni su qualsiasi articolo a cui siamo interessati. Per farlo, dobbiamo modificare la nostra funzione, in modo da poter passare un valore per ogni ID articolo.

Possiamo modificare la nostra funzione connettore per accettare qualsiasi valore, configurando gli input. Gli input consentono di prelevare valori dalle applicazioni e di passarli alle funzioni del connettore.

La configurazione degli input avviene in due parti: 1.) creazione di un input nel riquadro degli input, 2.) specificazione del punto in cui l'input verrà utilizzato nella funzione del connettore.

Per prima cosa, si aggiunge un campo al riquadro di input. È possibile modificare il tipo di dati di un input facendo clic sull'icona accanto al nome dell'input. Assicurarsi che il tipo selezionato corrisponda al tipo di origine che si utilizzerà nelle applicazioni. Il campo accanto al nome dell'input può essere usato per testare i valori da passare nella funzione del connettore e per simulare gli input delle applicazioni.

Successivamente, occorre specificare dove l'input verrà utilizzato nella funzione del connettore. Gli input sono accessibili in tutta la funzione del connettore, anche nell'URL dell'endpoint, nei parametri della query e negli estrattori JSON degli output. Per ulteriori informazioni sulla configurazione di una particolare funzione, consultare la documentazione API di ogni servizio che si desidera utilizzare.

Nel nostro esempio, possiamo accedere a un particolare articolo specificandolo alla fine del percorso dell'endpoint, o al posto di "{articleId}".

Utilizzando gli input, possiamo passare dinamicamente un valore in questo URL e quindi utilizzare questa funzione connettore per ottenere informazioni su qualsiasi articolo desiderato.

Si aggiungono gli input al percorso dell'endpoint mettendo un segno di dollaro**($**) prima e dopo il parametro (in questo caso, "ID"). La stringa tra il segno del dollaro è sensibile alle maiuscole e deve corrispondere esattamente al nome dell'input. Se torniamo al nostro esempio, cambiamo l'URL in modo che l'ID sia allineato con il nostro input. Il testo tra i segni di dollaro si trasforma in un blocco, che indica una proprietà, in questo modo:

Ora possiamo impostare l'ID come valore di input, anziché codificarlo direttamente nell'URL dell'endpoint.

Per aggiungere altri input, fare clic sul simbolo + nell'angolo in alto a destra della casella degli input.

Parametri

I parametri della query sono coppie chiave-valore che appaiono dopo il ? nell'endpoint o sotto i parametri della query quando si crea una funzione del connettore.

Ora che abbiamo impostato i nostri input, è possibile creare alcuni parametri per modificare i risultati del test e assicurarsi di ottenere solo le informazioni desiderate. Trovare le chiavi e i valori di questi parametri nella documentazione API del server a cui ci si connette.

Con le coppie Chiave-Valore, uno dei componenti è una "Chiave" e l'altro è il "Valore"; entrambi vengono aggiunti alla fine dell'URL del collegamento al modulo. Pensate a queste coppie come a dei token in un'e-mail per personalizzare il nome di una persona. L'uso di coppie chiave-valore consente di passare informazioni a un modulo.

La chiave indica il nome di una variabile.

Il valore indica il valore di una proprietà.

In questo esempio, vogliamo impostare un parametro che garantisca che l'articolo restituito sia pubblicato sul sito della Knowledge Base. Inserendo le informazioni fornite nella documentazione dell'API, il parametro si presenta come segue:

Questi parametri di query e di richiesta sono campi opzionali da compilare, ma forniscono una specificità ai risultati del test, se necessario.

{{glossario.Output}}s

Gli output sono la parte della funzione connettore che mostra quali informazioni vengono restituite direttamente. Sono strutturati in notazione a punti, quindi occorre prestare molta attenzione al formato dei risultati dei test per verificare che la notazione segua un percorso preciso. Gli output corrispondono alle variabili delle applicazioni, quindi assicuratevi di assegnare loro un nome unico e identificabile.

Si noti che è possibile cambiare il tipo di output in elenchi utilizzando il Toggle Elenco; questa opzione annida gli output delle variabili all'interno degli oggetti e mappa universalmente il percorso della notazione a punti per tutti gli output annidati in un elenco di oggetti.

Per verificare se le uscite sono state mappate correttamente, fate clic sulla scheda Uscite nel riquadro Risultati del test e annotate i risultati restituiti.

Se le uscite corrispondono ai risultati, congratulazioni! Avete creato una funzione di connettore funzionante e siete pronti a utilizzarla nelle applicazioni. Per i passi successivi, consultare la sezione Uso dei connettori HTTP nelle applicazioni.

Se il problema è che la funzione connettore non funziona correttamente, consultate la nostra Guida alla risoluzione dei problemi per capire cosa potrebbe essere andato storto.

Seguite il corso HTTP Connectors University per un approfondimento sulla costruzione dei connettori.

Ulteriori letture

• Come formattare gli output dei connettori HTTP

Avete trovato quello che cercavate?

Potete anche andare su community.tulip.co per porre la vostra domanda o vedere se altri hanno affrontato una questione simile!