Як викликати зовнішній API з Workspace Studio

Робочий процес Google Workspace Studio може потребувати даних з-поза Gmail, Диска або Chat: статус замовлення, номер із бази даних або відповідь із внутрішнього інструменту. Щоб отримати ці дані або надіслати інформацію до іншого сервісу, можна додати крок Надіслати вебхукЦе створює HTTP-запит на адресу вказаного вами API.

Вам не потрібно налаштовувати виклик функції Gemini для здійснення цього запиту. У Workspace Studio потік виконує крок вебхука та отримує відповідь. Потім, якщо ви вважаєте це корисним, ви можете передати цю відповідь іншому кроку, щоб підсумувати її, витягти дані або повідомити результат.

Що потрібно перед підключенням до 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. ОТРИМАТИ Він використовується для запиту даних; ПОШТАщоб надіслати їх або створити запис. Вони також доступні ВСТАВИТИ, ВИПРАВТИ та ВИДАЛИТИ.
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-відповіді. Це рішення вимагає розробки та належного налаштування дозволів; це не обов'язково для простих запитів, які вже може обробляти нативний крок.

Уникайте вставляння закритих ключів у видимі поля потоку або вбудовування їх у спільну URL-адресу. Перш ніж надсилати дані з Gmail, Chat або Calendar, перевірте, яку інформацію отримуватиме зовнішній сервіс і чи має він право на її обробку.

Як знайти помилки у вебхуку

Якщо з’єднання не вдається, відкрийте вкладку Активність потоку. Там ви можете переглянути повну помилку та відповідь, надіслану цільовим сервером. Ця інформація допомагає розрізнити проблему конфігурації Studio та запит, відхилений API.

• Крок не відображається: Зверніться до адміністратора, чи ввімкнено вебхуки для вашого організаційного підрозділу.
• URL-адресу заблоковано: Перевірте список дозволених адрес, якщо ваша редакція використовує це обмеження.
• Помилка 400: перевірте формат тіла та поля, необхідні API.
• Помилка 401 або 403: Перегляньте дозволи та метод автентифікації, необхідні для служби.
• Помилка 429: Перевірте, чи не перевищено ліміт запитів для цільового API.
• Помилка 500: Перевірте статус та записи служби, яка отримує запит.

Також пам’ятайте про загальні обмеження Workspace Studio: наразі він підтримує до 25 потоків на користувача y 20 кроків на потікКрім того, існує ліміт комбінованого виконання, який скидається кожні 24 години. Якщо кілька потоків зупиняються, перегляньте їхню активність, перш ніж пояснювати збій API.

Для більшості простих HTTP-з’єднань процес є простим: увімкніть вебхук, налаштуйте фіксовану URL-адресу та правильний метод, перевірте запит і використовуйте відповідь у наступних кроках. Якщо інтеграція вимагає розширеної автентифікації або перетворення даних за допомогою коду, тоді має сенс підготувати власний крок.