Ulkoisen API:n kutsuminen Workspace Studiosta

Google Workspace Studio -työnkulku saattaa tarvita tietoja Gmailin, Driven tai Chatin ulkopuolelta: tilauksen tilan, numeron tietokannasta tai vastauksen sisäisestä työkalusta. Voit hakea nämä tiedot tai lähettää tietoja toiseen palveluun lisäämällä vaiheen Lähetä webhookTämä tekee HTTP-pyynnön määrittämäsi API-osoitteeseen.

Sinun ei tarvitse määrittää Gemini-funktiokutsua kyseisen pyynnön tekemiseksi. Workspace Studiossa työnkulku suorittaa webhook-vaiheen ja vastaanottaa vastauksen. Sitten, jos pidät sitä hyödyllisenä, voit välittää vastauksen toiseen vaiheeseen sen yhteenvetoa, datan poimimista tai tuloksen viestimistä varten.

Mitä tarvitset ennen API-yhteyden muodostamista

Ensimmäinen vaihe on varmistaa, että organisaatiosi voi käyttää webhookeja. Funktio sijaitsee osoitteessa rajoitettu esikatselu ja on oletusarvoisesti poissa käytöstä. Järjestelmänvalvojan on kirjauduttava sisään. Sovellukset > Google Workspace > Workspace Studio > Webhook-asetukset ja ota se käyttöön vastaavassa organisaatioyksikössä.

Joissakin versioissa järjestelmänvalvoja voi myös rajoittaa yhteydet yhteen sallittujen verkkotunnusten ja URL-osoitteiden luetteloJos vaihe näkyy Studiossa, mutta se ei kommunikoi API:si kanssa, varmista, että kohdeosoite on valtuutettu. Lisäksi oletusarvoisesti webhookkeja sisältävät toiminnot edellyttävät käyttäjältä vaiheen tarkistamista ja vahvistamista ennen sen suorittamista.

Ulkoisesta palvelusta sinun on tiedettävä sen URL-osoite, sen tukemat HTTP-metodit ja sen odottama tietomuoto. Tarkista myös, miten se todentaa tiedot: julkisella, vain luku -tilassa olevalla API:lla on erilaiset vaatimukset kuin yksityisellä API:lla, joka vaatii tokeneita tai erityisiä otsikoita.

API:n kutsuminen Workspace Studiosta vaihe vaiheelta

Syötä studio.workspace.google.com ja luo työnkulku tarvitsemallasi liipaisimella. Voit esimerkiksi käynnistää sen, kun tietyt ehdot täyttävä sähköposti saapuu. Toimi sitten seuraavasti:

1. Lehdistö Lisää vaihe ja valitse Lähetä webhook.
2. Syötä Koko URL-osoite API:sta, mukaan lukien etuliite https://Osoite on korjattava: tämä kenttä ei tue virtausmuuttujia.
3. Valitse HTTP-menetelmä. SAADA Sitä käytetään tietojen kyselyyn; LÄHETTÄÄlähettääksesi ne tai luodaksesi tietueen. Ne ovat myös saatavilla PUT, PATCH ja DELETE.
4. Jos API vaatii rungon, kirjoita se sisältökenttään tai hyötykuormaGoogle suosittelee JSON-muotoilua, kun vastaanottava palvelu sitä odottaa.
5. Tee testin suorittaminenTarkista tulos ja aktivoi työnkulku, kun olet varmistanut sen toimivuuden.

Muista, että testi suorita toimintoJos määrität POST-komennon luomaan tietueen tai DELETE-komennon poistamaan sen, käytä ensin testiympäristöä tai dataa, jota voit muokata ongelmitta.

Esimerkki: ilmoituksen lähettäminen ulkoiseen työkaluun

Kuvittele, että tiimilläsi on API, joka luo hälytyksiä https://api.ejemplo.com/v1/avisosTämä osoite on havainnollistavaSinun on korvattava se palvelusi sisällöllä. Jos sen dokumentaatio osoittaa, että se hyväksyy POST- ja JSON-rungon, voit määrittää vaiheen sisällöllä, kuten {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Voit myös lisätä virtausmuuttuja Esimerkiksi tekstiin lisätäksesi sähköpostin aiheen, joka laukaisi sen. Tee tämä Studion muuttujavalitsimella ja tarkista tulos: jos lisätty teksti sisältää lainausmerkkejä tai muita erikoismerkkejä, se voi jättää JSON-tiedoston virheelliseksi. Muuttujia voidaan käyttää sisällössä, mutta ei URL-kentässä.

Jos sinun on noudettava tietoja, valitse GET ja anna kiinteä URL-osoite, joka sisältää jo tarvittavat parametrit. Workspace Studio jättää huomiotta kaiken GET-pyynnön runkoon kirjoittamasi sisällön.

Mitä tehdä API-vastaukselle

Webhook-vaihe jättää palveluvastaus tekstinä muuttujassa, joka on käytettävissä seuraavissa vaiheissa. Voit käyttää sitä ilmoituksen lähettämiseen, yhteenvedon kirjoittamiseen tai tekoälyvaiheen pyytämiseen tiettyjen tietojen poimimiseksi.

Jos API esimerkiksi palauttaa tilauksen tilan, seuraava vaihe voi viestiä kyseisen tilan tiimille. Valitse erikseen vastauksen sisältävä muuttuja: seuraavat vaiheet eivät automaattisesti vastaanota kaikkea, mikä tapahtui aiemmin kulussa. On suositeltavaa testata palautettu sisältö ennen siitä riippuvien ohjeiden kirjoittamista.

Jos API vaatii todennusta tai monimutkaisempaa logiikkaa

Dokumentoitu peruskonfiguraatio kohteelle Lähetä webhook Se sisältää URL-osoitteen, metodin ja valinnaisen rungon. Jos integraatiosi tarvitsee OAuth-tokenin, URL-osoitteen luomisen muuttuvilla parametreilla, tiettyjen otsikoiden lisäämisen tai vastauksen muokkaamisen ennen jatkamista, tarkista, kattaako tämä vaihe nämä vaatimukset.

Kun se ei riitä, yksi vaihtoehto on kehittää Mukautettu vaihe Workspace Studiolle laajennuksen kautta. Google Apps Script -toteutuksessa palvelu UrlFetchApp Sen avulla voit tehdä pyyntöjä ulkoisille API-rajapinnoille ja käsitellä JSON-vastauksia. Tämä ratkaisu vaatii kehitystä ja asianmukaista käyttöoikeuksien määrittämistä; se ei ole välttämätöntä yksinkertaisille pyynnöille, joita natiivivaihe jo pystyy käsittelemään.

Vältä yksityisten avainten liittämistä työnkulun näkyviin kenttiin tai niiden upottamista jaettuun URL-osoitteeseen. Ennen kuin lähetät tietoja Gmailista, Chatista tai Kalenterista, tarkista, mitä tietoja ulkoinen palvelu vastaanottaa ja onko sillä valtuudet käsitellä niitä.

Kuinka löytää virheitä webhookista

Jos yhteys katkeaa, avaa välilehti Toiminta työnkulusta. Siellä voit tarkastella koko virhettä ja kohdepalvelimen lähettämää vastausta. Nämä tiedot auttavat erottamaan Studio-määritysongelman API:n hylkäämästä pyynnöstä.

• Vaihe ei näy: Tarkista järjestelmänvalvojaltasi, ovatko webhookit käytössä organisaatioyksikössäsi.
• URL-osoite on estetty: Tarkista sallittujen osoitteiden luettelo, jos versiosi käyttää kyseistä rajoitusta.
• Virhe 400: Tarkista leipätekstin muoto ja API:n vaatimat kentät.
• Virhe 401 tai 403: Tarkista palvelun edellyttämät käyttöoikeudet ja todennusmenetelmä.
• Virhe 429: Tarkista, oletko ylittänyt kohde-API:n pyyntörajan.
• Virhe 500: Tarkista pyynnön vastaanottaneen palvelun tila ja tiedot.

Muista myös Workspace Studion yleiset rajoitukset: se tukee tällä hetkellä jopa 25 työnkulkua käyttäjää kohden y 20 askelta per virtausLisäksi on olemassa yhdistetty suoritusrajoitus, joka nollautuu 24 tunnin välein. Jos useita työnkulkuja lakkaa toimimasta, tarkista niiden toiminta ennen kuin määrität virheen johtuvan API:sta.

Useimmille yksinkertaisille HTTP-yhteyksille prosessi on suoraviivainen: ota webhook käyttöön, määritä kiinteä URL-osoite ja oikea metodi, testaa pyyntö ja käytä vastausta seuraavissa vaiheissa. Jos integrointi vaatii edistynyttä todennusta tai datan muuntamista koodin avulla, on järkevää valmistella mukautettu vaihe.