Cum se apelează o API externă din Workspace Studio

Un flux de lucru Google Workspace Studio ar putea necesita date din afara Gmail, Drive sau Chat: starea comenzii, un număr dintr-o bază de date sau un răspuns de la un instrument intern. Pentru a recupera aceste date sau a trimite informații către un alt serviciu, puteți adăuga pasul Trimiteți un webhookAceasta face o cerere HTTP către adresa unui API pe care l-ați specificat.

Nu este nevoie să configurați apelul funcției Gemini pentru a face acea solicitare. În Workspace Studio, fluxul execută pasul webhook și primește răspunsul. Apoi, dacă îl considerați util, puteți transmite acel răspuns unui alt pas pentru a-l rezuma, a extrage date sau a comunica rezultatul.

Ce este necesar înainte de a vă conecta la o API

Primul pas este să verificați dacă organizația dvs. poate utiliza webhook-uri. Funcția se află în previzualizare limitată și este dezactivat în mod implicit. Un administrator trebuie să se conecteze. Aplicații > Google Workspace > Workspace Studio > Setări Webhook și activați-l pentru unitatea organizațională corespunzătoare.

În unele ediții, administratorul poate, de asemenea, limita conexiunile la una listă de domenii și adrese URL permiseDacă pasul apare în Studio, dar nu reușește să comunice cu API-ul dvs., verificați dacă adresa de destinație este autorizată. De asemenea, în mod implicit, acțiunile care implică webhook-uri necesită ca utilizatorul să revizuiască și să confirme pasul înainte de execuție.

De la serviciul extern, trebuie să cunoașteți adresa URL a acestuia, metodele HTTP pe care le acceptă și formatul de date așteptat. De asemenea, verificați modul în care se autentifică: o API publică doar pentru citire are cerințe diferite față de o API privată care necesită token-uri sau anteturi speciale.

Cum se apelează o API din Workspace Studio pas cu pas

Introduceți studio.workspace.google.com și creați un flux de lucru cu declanșatorul de care aveți nevoie. De exemplu, îl puteți porni atunci când sosește un e-mail care îndeplinește anumite condiții. Apoi, urmați acești pași:

1. Presa Adăugați un pas și selectați Trimiteți un webhook.
2. Introduceți URL complet al API-ului, inclusiv prefixul https://Adresa trebuie să fie fixă: acest câmp nu acceptă variabile de flux.
3. Selectați metoda HTTP. OBŢINE Se folosește pentru interogarea datelor; POSTpentru a le trimite sau a crea o înregistrare. De asemenea, sunt disponibile PUT, PATCH și DELETE.
4. Dacă API-ul necesită un corp, scrieți-l în câmpul de conținut sau încărcătură utilăGoogle recomandă utilizarea JSON atunci când serviciul receptor o așteaptă.
5. Faceți o execuția testuluiVerifică rezultatul și activează fluxul după ce ai verificat că funcționează.

Rețineți că testul efectuați acțiuneaDacă configurați o comandă POST pentru a crea o înregistrare sau o comandă DELETE pentru a o șterge, utilizați mai întâi un mediu de testare sau date pe care le puteți modifica fără probleme.

Exemplu: trimiterea unei notificări către un instrument extern

Imaginează-ți că echipa ta are o interfață de programare (API) care creează alerte în https://api.ejemplo.com/v1/avisosAceastă adresă este ilustrativVa trebui să îl înlocuiești cu cel de la serviciul tău. Dacă documentația sa indică faptul că acceptă POST și un corp JSON, poți configura pasul cu conținut de genul {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

De asemenea, puteți introduce un variabilă de debit În corp, de exemplu, pentru a include subiectul e-mailului care l-a declanșat. Faceți acest lucru din selectorul de variabile din Studio și verificați rezultatul: dacă textul inserat conține ghilimele sau alte caractere speciale, este posibil ca JSON-ul să rămână incorect. Variabilele pot fi utilizate în conținut, dar nu în câmpul URL.

Dacă trebuie să recuperați date, alegeți GET și introduceți o adresă URL fixă ​​care conține deja parametrii necesari. Workspace Studio va ignora orice conținut pe care l-ați scris în corpul unei solicitări GET.

Ce se poate face cu răspunsul API

Pasul webhook părăsește răspunsul serviciului sub formă de text într-o variabilă disponibilă pentru pașii următori. O puteți folosi pentru a trimite o notificare, a scrie un rezumat sau a solicita unui pas al inteligenței artificiale să extragă date specifice.

De exemplu, dacă API-ul returnează starea unei comenzi, pasul următor poate comunica acea stare echipei. Selectați explicit variabila care conține răspunsul: pașii ulteriori nu primesc automat tot ce s-a întâmplat anterior în flux. Este recomandabil să testați conținutul returnat înainte de a scrie instrucțiuni care depind de acesta.

Dacă API-ul necesită autentificare sau o logică mai complexă

Configurația de bază documentată pentru Trimiteți un webhook Include adresa URL, metoda și un corp opțional. Dacă integrarea dvs. trebuie să obțină un token OAuth, să construiască o adresă URL cu parametri variabili, să adauge anteturi specifice sau să transforme un răspuns înainte de a continua, verificați dacă acest pas acoperă aceste cerințe.

Când acest lucru nu este suficient, o opțiune este dezvoltarea unui Pas personalizat pentru Workspace Studio prin intermediul unui plugin. Într-o implementare Google Apps Script, serviciul UrlFetchApp Îți permite să faci cereri către API-uri externe și să procesezi răspunsuri JSON. Această soluție necesită dezvoltare și o configurare adecvată a permisiunilor; nu este necesară pentru cereri simple pe care pasul nativ le poate deja gestiona.

Evitați să lipiți chei private în câmpuri vizibile ale fluxului sau să le încorporați într-o adresă URL partajată. Înainte de a trimite date din Gmail, Chat sau Calendar, verificați ce informații va primi serviciul extern și dacă este autorizat să le proceseze.

Cum să localizezi erorile într-un webhook

Dacă conexiunea eșuează, deschideți fila Activitate a fluxului. Acolo puteți vizualiza eroarea completă și răspunsul trimis de serverul de destinație. Aceste informații ajută la distingerea între o problemă de configurare Studio și o solicitare respinsă de API.

• Pasul nu apare: Verifică cu administratorul dacă webhook-urile sunt activate pentru unitatea ta organizațională.
• URL-ul este blocat: Verificați lista adreselor permise, dacă ediția dvs. utilizează restricția respectivă.
• Eroarea 400: verificați formatul corpului și câmpurile solicitate de API.
• Eroare 401 sau 403: Examinați permisiunile și metoda de autentificare necesare serviciului.
• Eroarea 429: Verificați dacă ați depășit limita de solicitări pentru API-ul țintă.
• Eroarea 500: Verificați starea și înregistrările serviciului care primește solicitarea.

De asemenea, rețineți limitările generale ale Workspace Studio: în prezent, acesta acceptă până la 25 de fluxuri per utilizator y 20 de pași per fluxÎn plus, există o limită de execuție combinată care se resetează la fiecare 24 de ore. Dacă mai multe fluxuri se opresc din rulare, verificați activitatea acestora înainte de a atribui eroarea API-ului.

Pentru majoritatea conexiunilor HTTP simple, procesul este simplu: activați webhook-ul, configurați o adresă URL fixă ​​și metoda corectă, testați solicitarea și utilizați răspunsul în pașii următori. Dacă integrarea necesită autentificare avansată sau transformarea datelor prin cod, atunci este logic să pregătiți un pas personalizat.