Jak wywołać zewnętrzne API z Workspace Studio

Przepływ pracy w Google Workspace Studio może wymagać danych spoza Gmaila, Dysku lub Czatu: statusu zamówienia, numeru z bazy danych lub odpowiedzi z narzędzia wewnętrznego. Aby pobrać te dane lub wysłać informacje do innej usługi, możesz dodać krok Wyślij webhookPowoduje wysłanie żądania HTTP na adres API, który podałeś.

Nie musisz konfigurować wywołania funkcji Gemini, aby wysłać to żądanie. W Workspace Studio przepływ wykonuje krok webhooka i odbiera odpowiedź. Następnie, jeśli uznasz ją za przydatną, możesz przekazać tę odpowiedź do innego kroku, aby ją podsumować, wyodrębnić dane lub przekazać wynik.

Czego potrzebujesz przed połączeniem się z API

Pierwszym krokiem jest sprawdzenie, czy Twoja organizacja może korzystać z webhooków. Funkcja ta znajduje się w ograniczony podgląd i jest domyślnie wyłączona. Administrator musi się zalogować. Aplikacje > Google Workspace > Workspace Studio > Ustawienia webhooka i włącz ją dla odpowiedniej jednostki organizacyjnej.

W niektórych edycjach administrator może również ograniczyć połączenia do jednego lista dozwolonych domen i adresów URLJeśli krok pojawia się w Studio, ale nie nawiązuje komunikacji z API, sprawdź, czy adres docelowy jest autoryzowany. Ponadto, domyślnie akcje wykorzystujące webhooki wymagają od użytkownika przejrzenia i potwierdzenia kroku przed jego wykonaniem.

W przypadku usługi zewnętrznej musisz znać jej adres URL, obsługiwane przez nią metody HTTP oraz oczekiwany format danych. Sprawdź również sposób uwierzytelniania: publiczne API tylko do odczytu ma inne wymagania niż prywatne API, które wymaga tokenów lub specjalnych nagłówków.

Jak krok po kroku wywołać API z Workspace Studio

Wchodzić studio.workspace.google.com i utwórz przepływ pracy z potrzebnym wyzwalaczem. Możesz go na przykład uruchomić po otrzymaniu wiadomości e-mail spełniającej określone warunki. Następnie wykonaj następujące kroki:

1. Naciskać Dodaj krok i wybierz Wyślij webhook.
2. Wejdź Pełny adres URL API, w tym prefiks https://Adres musi być stały: to pole nie obsługuje zmiennych przepływu.
3. Wybierz metodę HTTP. DOSTAWAĆ Służy do wyszukiwania danych; POSTaby je wysłać lub utworzyć rekord. Są one również dostępne PUT, PATCH i DELETE.
4. Jeżeli API wymaga treści, wpisz ją w polu treści lub ładunekGoogle zaleca używanie formatu JSON, jeśli usługa odbiorcza tego oczekuje.
5. Zrób wykonanie testuSprawdź wynik i aktywuj przepływ po upewnieniu się, że działa.

Pamiętaj, że test wykonać czynnośćJeśli skonfigurujesz instrukcję POST w celu utworzenia rekordu lub instrukcję DELETE w celu jego usunięcia, najpierw użyj środowiska testowego lub danych, które możesz modyfikować bez problemów.

Przykład: wysyłanie powiadomienia do narzędzia zewnętrznego

Wyobraź sobie, że Twój zespół ma API, które tworzy alerty w https://api.ejemplo.com/v1/avisosTen adres to ilustracyjnyMusisz go zastąpić tym ze swojej usługi. Jeśli w dokumentacji jest napisane, że akceptuje ona POST i treść JSON, możesz skonfigurować krok z taką zawartością, jak {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Możesz również wstawić zmienna przepływu Na przykład w treści, aby uwzględnić temat wiadomości e-mail, która ją wywołała. Zrób to z selektora zmiennych w Studio i sprawdź wynik: jeśli wstawiony tekst zawiera cudzysłowy lub inne znaki specjalne, może to spowodować nieprawidłowy format pliku JSON. Zmienne mogą być używane w treści, ale nie w polu adresu URL.

Jeśli chcesz pobrać dane, wybierz GET i wprowadź stały adres URL, który zawiera już niezbędne parametry. Workspace Studio zignoruje wszelką treść wpisaną w treści żądania GET.

Co zrobić z odpowiedzią API

Krok webhooka pozostawia odpowiedź serwisu w formie tekstu w zmiennej dostępnej dla kolejnych kroków. Możesz jej użyć do wysłania powiadomienia, napisania podsumowania lub zlecenia sztucznie stworzonej sztucznej inteligencji wyodrębnienia określonych danych.

Na przykład, jeśli API zwraca status zamówienia, kolejny krok może przekazać ten status zespołowi. Należy jawnie wybrać zmienną zawierającą odpowiedź: kolejne kroki nie otrzymują automatycznie wszystkich informacji, które wystąpiły wcześniej w przepływie. Zaleca się przetestowanie zwróconej treści przed napisaniem instrukcji, które od niej zależą.

Jeśli API wymaga uwierzytelniania lub bardziej złożonej logiki

Udokumentowana podstawowa konfiguracja dla Wyślij webhook Zawiera adres URL, metodę i opcjonalną treść. Jeśli Twoja integracja wymaga uzyskania tokenu OAuth, utworzenia adresu URL ze zmiennymi parametrami, dodania określonych nagłówków lub przekształcenia odpowiedzi przed kontynuacją, sprawdź, czy ten krok spełnia te wymagania.

Jeśli to nie wystarczy, jedną z opcji jest opracowanie Niestandardowy krok dla Workspace Studio za pośrednictwem wtyczki. W implementacji Google Apps Script usługa UrlFetchApp Umożliwia wysyłanie żądań do zewnętrznych interfejsów API i przetwarzanie odpowiedzi JSON. To rozwiązanie wymaga programowania i odpowiedniej konfiguracji uprawnień; nie jest konieczne w przypadku prostych żądań, które natywny krok może już obsłużyć.

Unikaj wklejania kluczy prywatnych w widoczne pola przepływu ani osadzania ich w udostępnionym adresie URL. Przed wysłaniem danych z Gmaila, Czatu lub Kalendarza sprawdź, jakie informacje otrzyma usługa zewnętrzna i czy jest upoważniona do ich przetwarzania.

Jak zlokalizować błędy w webhooku

Jeśli połączenie się nie powiedzie, otwórz kartę Działalność przepływu. Tam możesz zobaczyć pełny błąd i odpowiedź wysłaną przez serwer docelowy. Te informacje pomagają odróżnić problem z konfiguracją Studio od żądania odrzuconego przez API.

• Krok się nie pojawia: Sprawdź u administratora, czy webhooki są włączone dla Twojej jednostki organizacyjnej.
• Adres URL jest zablokowany: Sprawdź listę dozwolonych adresów, jeśli Twoja edycja korzysta z tego ograniczenia.
• Błąd 400: sprawdź format treści i pola wymagane przez API.
• Błąd 401 lub 403: Sprawdź uprawnienia i metodę uwierzytelniania wymaganą przez usługę.
• Błąd 429: Sprawdź, czy nie przekroczono limitu żądań dla docelowego interfejsu API.
• Błąd 500: Sprawdź status i rejestr usługi otrzymującej żądanie.

Należy również pamiętać o ogólnych ograniczeniach Workspace Studio: obecnie obsługuje ono do 25 przepływów na użytkownika y 20 kroków na przepływDodatkowo obowiązuje limit łącznej liczby wykonań, który resetuje się co 24 godziny. Jeśli wiele przepływów przestanie działać, należy sprawdzić ich aktywność przed przypisaniem awarii do interfejsu API.

W przypadku większości prostych połączeń HTTP proces jest prosty: włącz webhook, skonfiguruj stały adres URL i poprawną metodę, przetestuj żądanie i wykorzystaj odpowiedź w kolejnych krokach. Jeśli integracja wymaga zaawansowanego uwierzytelniania lub transformacji danych za pomocą kodu, warto przygotować krok niestandardowy.