Ako volať externé API z Workspace Studio

Pracovný postup služby Google Workspace Studio môže vyžadovať údaje mimo Gmailu, Disku alebo Chatu: stav objednávky, číslo z databázy alebo odpoveď z interného nástroja. Ak chcete tieto údaje načítať alebo odoslať informácie do inej služby, môžete pridať krok Odoslať webhookToto odošle HTTP požiadavku na adresu API, ktorú ste zadali.

Na vykonanie tejto požiadavky nemusíte konfigurovať volanie funkcie Gemini. V aplikácii Workspace Studio postup vykoná krok webhooku a dostane odpoveď. Ak to potom považujete za užitočné, môžete túto odpoveď postúpiť ďalšiemu kroku, aby ste ju zhrnuli, extrahovali údaje alebo oznámili výsledok.

Čo potrebujete pred pripojením k API

Prvým krokom je overiť, či vaša organizácia môže používať webhooky. Funkcia sa nachádza v obmedzený náhľad a je predvolene vypnuté. Musí sa prihlásiť správca. Aplikácie > Google Workspace > Workspace Studio > Nastavenia webhooku a povoliť ho pre príslušnú organizačnú jednotku.

V niektorých vydaniach môže správca tiež obmedziť pripojenia na jedno zoznam povolených domén a URL adriesAk sa krok zobrazí v aplikácii Studio, ale nepodarí sa mu komunikovať s vaším rozhraním API, overte, či je cieľová adresa autorizovaná. Akcie zahŕňajúce webhooky tiež štandardne vyžadujú, aby si používateľ pred vykonaním kroku skontroloval a potvrdil.

Z externej služby potrebujete poznať jej URL adresu, HTTP metódy, ktoré podporuje, a očakávaný formát údajov. Skontrolujte tiež, ako sa autentifikuje: verejné API iba na čítanie má iné požiadavky ako súkromné ​​API, ktoré vyžaduje tokeny alebo špeciálne hlavičky.

Ako krok za krokom volať API z Workspace Studio

Zadajte studio.workspace.google.com a vytvorte pracovný postup s potrebným spúšťačom. Môžete ho napríklad spustiť, keď príde e-mail, ktorý spĺňa určité podmienky. Potom postupujte podľa týchto krokov:

1. Tlač Pridať krok a vyberte Odoslať webhook.
2. Zadajte Celá URL adresa rozhrania API vrátane predpony https://Adresa musí byť pevne stanovená: toto pole nepodporuje premenné toku.
3. Vyberte metódu HTTP. ZÍSKAŤ Používa sa na dotazovanie údajov; POŠTAich poslať alebo vytvoriť záznam. Sú tiež k dispozícii VLOŽIŤ, ZÁPLATIŤ a ODSTRÁNIŤ.
4. Ak API vyžaduje telo, napíšte ho do poľa obsahu alebo užitočné zaťaženieGoogle odporúča použiť JSON, keď ho prijímajúca služba očakáva.
5. Vytvorte vykonanie testuSkontrolujte výsledok a po overení fungovania aktivujte tok.

Majte na pamäti, že test vykonať akciuAk nakonfigurujete POST na vytvorenie záznamu alebo DELETE na jeho odstránenie, najprv použite testovacie prostredie alebo dáta, ktoré môžete bez problémov upravovať.

Príklad: odoslanie oznámenia externému nástroju

Predstavte si, že váš tím má API, ktoré vytvára upozornenia v https://api.ejemplo.com/v1/avisosTáto adresa je ilustratívnyBudete ho musieť nahradiť tým z vašej služby. Ak dokumentácia uvádza, že akceptuje POST a telo JSON, môžete tento krok nakonfigurovať s obsahom ako {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Môžete tiež vložiť premenná prietoku Napríklad v tele správy, aby ste zahrnuli predmet e-mailu, ktorý ju spustil. Urobte to pomocou selektora premenných v programe Studio a skontrolujte výsledok: ak vložený text obsahuje úvodzovky alebo iné špeciálne znaky, môže to spôsobiť chybný formát JSON. Premenné sa dajú použiť v obsahu, ale nie v poli URL.

Ak potrebujete načítať dáta, vyberte GET a zadajte pevnú URL adresu, ktorá už obsahuje potrebné parametre. Workspace Studio bude ignorovať akýkoľvek obsah, ktorý ste napísali v tele požiadavky GET.

Čo robiť s odpoveďou API

Krok webhooku opúšťa odpoveď služby ako text v premennej dostupnej pre nasledujúce kroky. Môžete ju použiť na odoslanie oznámenia, napísanie súhrnu alebo požiadať krok umelej inteligencie o extrahovanie konkrétnych údajov.

Napríklad, ak API vráti stav objednávky, ďalší krok môže tento stav oznámiť tímu. Explicitne vyberte premennú obsahujúcu odpoveď: nasledujúce kroky automaticky nedostanú všetko, čo sa stalo skôr v postupe. Pred napísaním inštrukcií, ktoré od neho závisia, je vhodné otestovať vrátený obsah.

Ak API vyžaduje autentifikáciu alebo zložitejšiu logiku

Zdokumentovaná základná konfigurácia pre Odoslať webhook Zahŕňa URL adresu, metódu a voliteľné telo. Ak vaša integrácia potrebuje získať token OAuth, vytvoriť URL adresu s variabilnými parametrami, pridať špecifické hlavičky alebo transformovať odpoveď pred pokračovaním, skontrolujte, či tento krok spĺňa tieto požiadavky.

Keď to nestačí, jednou z možností je vyvinúť Vlastný krok pre Workspace Studio prostredníctvom doplnku. V implementácii skriptu Google Apps Script služba UrlFetchApp Umožňuje vám zasielať požiadavky do externých API a spracovávať odpovede JSON. Toto riešenie vyžaduje vývoj a správnu konfiguráciu oprávnení; nie je to potrebné pre jednoduché požiadavky, ktoré už dokáže spracovať natívny krok.

Nevkladajte súkromné ​​kľúče do viditeľných polí postupu ani ich nevkladajte do zdieľanej URL adresy. Pred odoslaním údajov z Gmailu, Chatu alebo Kalendára overte, aké informácie externá služba dostane a či je oprávnená ich spracovať.

Ako nájsť chyby vo webhooku

Ak sa pripojenie nepodarí, otvorte kartu Aktivita postupu. Tam si môžete pozrieť celú chybu a odpoveď odoslanú cieľovým serverom. Tieto informácie pomáhajú rozlíšiť medzi problémom s konfiguráciou Studio a požiadavkou odmietnutou rozhraním API.

• Krok sa nezobrazuje: Overte si u svojho administrátora, či sú pre vašu organizačnú jednotku povolené webhooky.
• URL adresa je blokovaná: Skontrolujte zoznam povolených adries, ak vaša edícia používa toto obmedzenie.
• Chyba 400: Skontrolujte formát tela a polia požadované rozhraním API.
• Chyba 401 alebo 403: Skontrolujte povolenia a metódu overovania, ktoré služba vyžaduje.
• Chyba 429: Skontrolujte, či ste prekročili limit požiadaviek pre cieľové API.
• Chyba 500: Skontrolujte stav a záznamy služby, ktorá prijala žiadosť.

Majte tiež na pamäti všeobecné obmedzenia aplikácie Workspace Studio: momentálne podporuje až 25 postupov na používateľa y 20 krokov na tokOkrem toho existuje kombinovaný limit vykonávania, ktorý sa resetuje každých 24 hodín. Ak sa prestane spúšťať viacero postupov, pred pripísaním zlyhania rozhraniu API skontrolujte ich aktivitu.

Pre väčšinu jednoduchých HTTP pripojení je proces priamočiary: povoľte webhook, nakonfigurujte pevnú URL adresu a správnu metódu, otestujte požiadavku a použite odpoveď v nasledujúcich krokoch. Ak integrácia vyžaduje pokročilé overovanie alebo transformáciu údajov prostredníctvom kódu, má zmysel pripraviť vlastný krok.