Как да извикам външен API от Workspace Studio

Работният процес в Google Workspace Studio може да се нуждае от данни извън Gmail, Диск или Чат: състояние на поръчка, номер от база данни или отговор от вътрешен инструмент. За да извлечете тези данни или да изпратите информация до друга услуга, можете да добавите стъпката Изпращане на уеб кукичкаТова прави HTTP заявка към адреса на посочения от вас API.

Не е необходимо да конфигурирате извикването на функцията Gemini, за да направите тази заявка. В Workspace Studio потокът изпълнява стъпката на webhook и получава отговора. След това, ако го намерите за полезно, можете да предадете този отговор на друга стъпка, за да го обобщите, да извлечете данни или да съобщите резултата.

Какво ви е необходимо, преди да се свържете с API

Първата стъпка е да проверите дали вашата организация може да използва уеб кукички. Функцията се намира в ограничен преглед и е деактивирано по подразбиране. Администратор трябва да влезе в системата. Приложения > Google Workspace > Workspace Studio > Настройки на уебкукичката и го активирайте за съответната организационна единица.

В някои издания администраторът може също да ограничи връзките до една списък с разрешени домейни и URL адресиАко стъпката се появи в Studio, но не успее да се свърже с вашия API, проверете дали адресът на местоназначение е оторизиран. Също така, по подразбиране действията, включващи уеб кукички, изискват потребителят да прегледа и потвърди стъпката преди изпълнение.

От външната услуга трябва да знаете нейния URL адрес, HTTP методите, които поддържа, и очаквания формат на данните. Също така, проверете как се удостоверява: публичният API само за четене има различни изисквания от частния API, който изисква токени или специални заглавки.

Как да извикате API от Workspace Studio стъпка по стъпка

Въведете studio.workspace.google.com и създайте работен процес с необходимия ви тригер. Например, можете да го стартирате, когато пристигне имейл, който отговаря на определени условия. След това изпълнете следните стъпки:

1. Преса Добавяне на стъпка и изберете Изпращане на уеб кукичка.
2. Въведете Пълен URL адрес на API, включително префикса https://Адресът трябва да бъде фиксиран: това поле не поддържа променливи на потока.
3. Изберете HTTP метода. ПОЛУЧИ Използва се за заявки към данни; ПУБЛИКАЦИЯда ги изпратите или да създадете запис. Те също са на разположение PUT, PATCH и DELETE.
4. Ако API изисква тяло, напишете го в полето за съдържание или полезен товарGoogle препоръчва използването на JSON, когато приемащата услуга го очаква.
5. Направете изпълнение на тестаПроверете резултата и активирайте потока, след като сте се уверили, че работи.

Имайте предвид, че тестът изпълни действиетоАко конфигурирате POST за създаване на запис или DELETE за изтриването му, първо използвайте тестова среда или данни, които можете да променяте без проблеми.

Пример: изпращане на известие до външен инструмент

Представете си, че вашият екип има API, който създава известия в https://api.ejemplo.com/v1/avisosТози адрес е илюстративенЩе трябва да го замените с този от вашата услуга. Ако документацията му показва, че приема POST и JSON тяло, можете да конфигурирате стъпката със съдържание като {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Можете също да вмъкнете променлива на потока В тялото, например, за да включите темата на имейла, който го е задействал. Направете това от селектора на променливи на Studio и проверете резултата: ако вмъкнатият текст съдържа кавички или други специални символи, това може да доведе до деформация на JSON. Променливите могат да се използват в съдържанието, но не е в полето за URL адрес.

Ако трябва да извлечете данни, изберете GET и въведете фиксиран URL адрес, който вече съдържа необходимите параметри. Workspace Studio ще игнорира всяко съдържание, което сте написали в тялото на GET заявка.

Какво да правим с отговора на API

Стъпката на уеб куката оставя отговор на услугата като текст в променлива, достъпна за следващи стъпки. Можете да я използвате, за да изпратите известие, да напишете обобщение или да поискате от стъпка с изкуствен интелект да извлече конкретни данни.

Например, ако API върне състоянието на поръчка, следващата стъпка може да съобщи това състояние на екипа. Изберете изрично променливата, съдържаща отговора: следващите стъпки не получават автоматично всичко, което се е случило по-рано в потока. Препоръчително е да тествате върнатото съдържание, преди да напишете инструкции, които зависят от него.

Ако API изисква удостоверяване или по-сложна логика

Документираната основна конфигурация за Изпращане на уеб кукичка Това включва URL адреса, метода и незадължителен текст. Ако вашата интеграция трябва да получи OAuth токен, да изгради URL адрес с променливи параметри, да добави специфични заглавки или да трансформира отговор, преди да продължите, проверете дали тази стъпка покрива тези изисквания.

Когато това не е достатъчно, една от възможностите е да се разработи Персонализирана стъпка за Workspace Studio чрез плъгин. В имплементация на Google Apps Script, услугата UrlFetchApp Позволява ви да правите заявки към външни API и да обработвате JSON отговори. Това решение изисква разработка и правилна конфигурация на разрешенията; не е необходимо за прости заявки, които native step вече може да обработи.

Избягвайте поставянето на частни ключове във видими полета на потока или вграждането им в споделен URL адрес. Преди да изпращате данни от Gmail, Chat или Calendar, проверете каква информация ще получи външната услуга и дали е оторизирана да я обработва.

Как да откриете грешки в уеб кукичка

Ако връзката не успее, отворете раздела Дейност на потока. Там можете да видите пълната грешка и отговора, изпратен от целевия сървър. Тази информация помага да се направи разграничение между проблем с конфигурацията на Studio и заявка, отхвърлена от API.

• Стъпката не се показва: Проверете с администратора си дали уеб кукичките са активирани за вашата организационна единица.
• URL адресът е блокиран: Проверете списъка с разрешени адреси, ако вашето издание използва това ограничение.
• Грешка 400: проверете формата на тялото и полетата, изисквани от API.
• Грешка 401 или 403: Прегледайте разрешенията и метода за удостоверяване, изисквани от услугата.
• Грешка 429: Проверете дали сте превишили лимита за заявки за целевия API.
• Грешка 500: Проверете състоянието и записите на услугата, която получава заявката.

Също така имайте предвид общите ограничения на Workspace Studio: в момента то поддържа до 25 потока на потребител y 20 стъпки на потокОсвен това има комбиниран лимит за изпълнение, който се нулира на всеки 24 часа. Ако няколко потока спрат да се изпълняват, прегледайте тяхната активност, преди да припишете неуспеха на API.

За повечето прости HTTP връзки процесът е лесен: активирайте уеб куката, конфигурирайте фиксиран URL адрес и правилния метод, тествайте заявката и използвайте отговора в следващите стъпки. Ако интеграцията изисква разширено удостоверяване или трансформиране на данни чрез код, тогава има смисъл да се подготви персонализирана стъпка.