Come chiamare un'API esterna da Workspace Studio

Un flusso di lavoro di Google Workspace Studio potrebbe richiedere dati esterni a Gmail, Drive o Chat: lo stato di un ordine, un numero da un database o una risposta da uno strumento interno. Per recuperare questi dati o inviare informazioni a un altro servizio, puoi aggiungere il passaggio Invia un webhookQuesto effettua una richiesta HTTP all'indirizzo di un'API da te specificata.

Non è necessario configurare la chiamata alla funzione Gemini per effettuare tale richiesta. In Workspace Studio, il flusso esegue il passaggio webhook e riceve la risposta. Successivamente, se lo si ritiene utile, è possibile passare tale risposta a un altro passaggio per riepilogarla, estrarre dati o comunicarne il risultato.

Cosa ti serve prima di connetterti a un'API

Il primo passo è verificare che la tua organizzazione possa utilizzare i webhook. La funzione si trova in anteprima limitata ed è disabilitato per impostazione predefinita. È necessario l'accesso da parte di un amministratore. App > Google Workspace > Workspace Studio > Impostazioni Webhook e abilitarlo per la corrispondente unità organizzativa.

In alcune edizioni, l'amministratore può anche limitare le connessioni a una Elenco dei domini e degli URL consentitiSe il passaggio viene visualizzato in Studio ma non riesce a comunicare con la tua API, verifica che l'indirizzo di destinazione sia autorizzato. Inoltre, per impostazione predefinita, le azioni che coinvolgono i webhook richiedono all'utente di rivedere e confermare il passaggio prima dell'esecuzione.

Dal servizio esterno, è necessario conoscere il suo URL, i metodi HTTP supportati e il formato dati previsto. Inoltre, è importante verificare come avviene l'autenticazione: un'API pubblica di sola lettura ha requisiti diversi rispetto a un'API privata che richiede token o intestazioni speciali.

Come chiamare un'API da Workspace Studio passo dopo passo

Entra studio.workspace.google.com e crea un flusso di lavoro con il trigger di cui hai bisogno. Ad esempio, puoi avviarlo quando arriva un'email che soddisfa determinate condizioni. Quindi, segui questi passaggi:

1. Premere Aggiungi passaggio e seleziona Invia un webhook.
2. Entra nel URL completo dell'API, incluso il prefisso https://L'indirizzo deve essere fisso: questo campo non supporta variabili di flusso.
3. Seleziona il metodo HTTP. OTTENERE Viene utilizzato per interrogare i dati; INVIAREper inviarli o creare un record. Sono anche disponibili INSERISCI, AGGIORNA E CANCELLA.
4. Se l'API richiede un corpo, scrivilo nel campo contenuto o carico utileGoogle consiglia di utilizzare JSON quando il servizio ricevente lo prevede.
5. Fare un esecuzione del testControlla il risultato e attiva il flusso solo dopo aver verificato che funzioni correttamente.

Tieni presente che il test eseguire l'azioneSe si configura un'operazione POST per creare un record o un'operazione DELETE per eliminarlo, è consigliabile utilizzare prima un ambiente di test o dati che si possono modificare senza problemi.

Esempio: invio di una notifica a uno strumento esterno

Immagina che il tuo team abbia un'API che crea avvisi in https://api.ejemplo.com/v1/avisosQuesto indirizzo è illustrativoDovrai sostituirlo con quello del tuo servizio. Se la sua documentazione indica che accetta POST e un corpo JSON, potresti configurare il passaggio con un contenuto come {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

È possibile anche inserire un variabile di flusso Nel corpo, ad esempio, per includere l'oggetto dell'email che lo ha attivato. Esegui questa operazione dal selettore di variabili di Studio e controlla il risultato: se il testo inserito contiene virgolette o altri caratteri speciali, il JSON potrebbe risultare malformato. Le variabili possono essere utilizzate nel contenuto, ma non nel campo URL.

Se devi recuperare dei dati, scegli GET e inserisci un URL fisso che contenga già i parametri necessari. Workspace Studio ignorerà qualsiasi contenuto tu abbia scritto nel corpo di una richiesta GET.

Cosa fare con la risposta dell'API

Il passaggio webhook lascia il risposta del servizio come testo in una variabile disponibile per i passaggi successivi. Puoi usarla per inviare una notifica, scrivere un riepilogo o chiedere a un passaggio di intelligenza artificiale di estrarre dati specifici.

Ad esempio, se l'API restituisce lo stato di un ordine, il passaggio successivo può comunicare tale stato al team. Seleziona esplicitamente la variabile contenente la risposta: i passaggi successivi non riceveranno automaticamente tutto ciò che è accaduto in precedenza nel flusso. Si consiglia di testare il contenuto restituito prima di scrivere istruzioni che dipendono da esso.

Se l'API richiede autenticazione o una logica più complessa

La configurazione di base documentata per Invia un webhook Include l'URL, il metodo e un corpo facoltativo. Se la tua integrazione necessita di ottenere un token OAuth, costruire un URL con parametri variabili, aggiungere intestazioni specifiche o trasformare una risposta prima di procedere, verifica se questo passaggio soddisfa tali requisiti.

Quando ciò non è sufficiente, un'opzione è quella di sviluppare un Passaggio personalizzato per Workspace Studio tramite un plugin. In un'implementazione di Google Apps Script, il servizio UrlFetchApp Consente di effettuare richieste ad API esterne ed elaborare risposte JSON. Questa soluzione richiede sviluppo e una corretta configurazione delle autorizzazioni; non è necessaria per le richieste semplici che il passaggio nativo può già gestire.

Evita di incollare le chiavi private nei campi visibili del flusso o di incorporarle in un URL condiviso. Prima di inviare dati da Gmail, Chat o Calendar, verifica quali informazioni riceverà il servizio esterno e se è autorizzato a elaborarle.

Come individuare gli errori in un webhook

Se la connessione fallisce, apri la scheda Attività del flusso. Lì è possibile visualizzare l'errore completo e la risposta inviata dal server di destinazione. Queste informazioni aiutano a distinguere tra un problema di configurazione di Studio e una richiesta rifiutata dall'API.

• Il passaggio non viene visualizzato: Contatta il tuo amministratore per verificare se i webhook sono abilitati per la tua unità organizzativa.
• L'URL è bloccato: Verifica l'elenco degli indirizzi consentiti, se la tua edizione prevede tale restrizione.
• Errore 400: Verifica il formato del corpo della richiesta e i campi richiesti dall'API.
• Errore 401 o 403: Esamina le autorizzazioni e il metodo di autenticazione richiesti dal servizio.
• Errore 429: Controlla se hai superato il limite di richieste per l'API di destinazione.
• Errore 500: Verifica lo stato e i dati del servizio che ha ricevuto la richiesta.

Tieni inoltre presente le limitazioni generali di Workspace Studio: attualmente supporta fino a 25 flussi per utente y 20 passaggi per flussoInoltre, esiste un limite di esecuzione combinato che si azzera ogni 24 ore. Se più flussi smettono di funzionare, è necessario esaminarne l'attività prima di attribuire l'errore all'API.

Per la maggior parte delle connessioni HTTP semplici, il processo è diretto: abilitare il webhook, configurare un URL fisso e il metodo corretto, testare la richiesta e utilizzare la risposta nei passaggi successivi. Se l'integrazione richiede un'autenticazione avanzata o la trasformazione dei dati tramite codice, è opportuno predisporre una procedura personalizzata.