Centro assistenza di Workiva

Nelle integrazioni dinamiche, soprattutto quando si utilizzano i connettori HTTP nei flussi di lavoro automatizzati (come le catene), è fondamentale gestire in modo efficace la risposta di una chiamata API. I parametri di output permettono agli utenti di catturare i dati essenziali restituiti dall'API, come il corpo della risposta, le intestazioni della risposta e il codice di stato, in modo da poterli utilizzare nelle fasi successive.

Quale problema risolve?

I parametri di output sono fondamentali per creare flussi di lavoro reattivi e intelligenti.

• Flussi di lavoro dinamici: I parametri di output permettono di adattare le azioni successive in base a ciò che l'API restituisce: ad esempio, estrarre un token, verificare l'esistenza di un record o confermare il successo di un'operazione.
• Automazione: Grazie all'acquisizione automatica dei valori, gli utenti evitano l'inserimento manuale o la codifica, consentendo ai flussi di lavoro di scalare con meno manutenzione.
• Integrazioni semplificate: La connessione di sistemi come server di autenticazione, CRM o API personalizzate diventa più semplice perché il connettore si adatta ai dati ricevuti.

A chi si rivolge?

• Sviluppatori e integratori: Coloro che costruiscono catene di automazione o integrazioni tra sistemi.
• Analisti di dati: Coloro che si affidano a flussi di dati accurati e in tempo reale per alimentare dashboard o report.
• Amministratori di sistema: Chi si occupa della manutenzione e della risoluzione dei problemi delle integrazioni: avere accesso ai parametri di output aiuta a individuare rapidamente i problemi.

Cosa sono i parametri di output?

I parametri di output di un connettore HTTP sono utilizzati per definire i risultati attesi di una richiesta HTTP, come le intestazioni della risposta, il corpo della risposta o il codice della risposta. Definiscono i risultati attesi di una richiesta HTTP, che possono essere riutilizzati nei nodi o nelle fasi logiche successive di una catena.

Esempi di parametri di output:

• Intestazioni della risposta: Metadati come il tipo di contenuto, il server o lo stato del limite di velocità.
• Corpo della risposta: Il contenuto effettivo restituito dall'API, in genere in formato JSON o XML.
• Codice di risposta: Indica il successo (200), l'errore del client (400), l'errore del server (500), ecc.

Esempio: Cattura di un token di accesso

Supponiamo che un'API restituisca un token come questo:

{"token_type": "Bearer", "expires_in": 600, "access_token": "<access_token_string>", "scope": "graph:write graph_api|r permessi|w ..." }

Puoi definire access_token come parametro di output e passarlo al passaggio successivo (ad esempio per autenticare un'altra chiamata API).

Perché è necessario il corpo della risposta?

Il corpo della risposta è il luogo in cui l'API restituisce le informazioni più importanti. Possono includere, ma non sono limitati a:

• ID di record appena creati
• Token di autenticazione
• Risultati delle query o carichi di dati

Senza accedere al corpo della risposta, sei limitato ai metadati, il che limita la dinamicità del tuo flusso di lavoro. 

Ora possiamo ottenere il access_token disponibile nel menu a tendina delle risposte.

Scenari comuni di gestione degli errori

Problemi tipici che si possono incontrare quando si lavora con i parametri di output:

• Errore: parametro di output non definito

  Causa e soluzione: La struttura del corpo della risposta è cambiata o è annidata. Conferma il percorso JSON corretto del campo.

• Errore: 401 Non autorizzato

  Causa e soluzione: Token mancante o scaduto. Assicurati che il token sia stato acquisito e passato correttamente.

• Errore: 500 Internal Server Error

  Causa e soluzione: Problema del server o carico di lavoro non valido. Controlla il corpo della risposta per saperne di più.

• Errore: JSON non valido

  Causa e soluzione: L'API restituisce una risposta malformata. Usa un blocco Try-Catch o convalida l'output prima dell'analisi.

Cos'è un Bearer Token e perché è necessario?

Il Bearer Token è un tipo di token di accesso utilizzato nell'autenticazione OAuth 2.0. Autorizza un utente o un'applicazione ad accedere a un'API. Si chiama "Bearer" perché il token viene inserito nell'intestazione della richiesta HTTP.

Esempio di intestazione:

Autorizzazione: Portatore <access_token>

Questo token è più sicuro dell'autenticazione di base perché:

• Scade, riducendo il rischio di fughe di token.
• Può contenere scopi e permessi.
• Separa l'autenticazione dall'autorizzazione.

Perché non usare l'autenticazione di base?

Sebbene l'Autenticazione di base invii un nome utente e una password codificati in ogni richiesta, essa: è meno sicura - le credenziali possono essere riutilizzate o intercettate:

• È meno sicuro: le credenziali possono essere riutilizzate o intercettate.
• Non può scadere facilmente o limitare l'accesso.
• Manca il controllo dei permessi basato sui token.

I token bearer supportano la scadenza dei token, il refresh e i permessi granulari, il che li rende una scelta migliore per le API moderne e la sicurezza di livello enterprise.