Na tej stronie opisaliśmy, jak skonfigurować webhook, aby wysyłać wiadomości asynchroniczne do pokoju Google Chat za pomocą zewnętrznych wyzwalaczy. Możesz na przykład skonfigurować aplikację monitorującą, aby powiadamiała personel dyżurny w Hangouts Chat o awarii serwera. Aby wysłać wiadomość synchroniczną za pomocą aplikacji Chat, przeczytaj artykuł Wysyłanie wiadomości.
W przypadku tego typu architektury użytkownicy nie mogą wchodzić w interakcje z webhookem ani podłączoną aplikacją zewnętrzną, ponieważ komunikacja jest jednokierunkowa. Webhooki nie są konwersacyjne. Nie może odpowiadać na wiadomości od użytkowników ani otrzymywać od nich zdarzeń interakcji z aplikacją Google Chat. Aby odpowiadać na wiadomości, zamiast webhooka utwórz aplikację do obsługi czatu.
Webhook nie jest technicznie aplikacją Google Chat (łączy aplikacje za pomocą standardowych żądań HTTP), ale na potrzeby uproszczenia na tej stronie jest tak nazywany. Każdy webhook działa tylko w pokoju czatu, w którym jest zarejestrowany. Wewnętrzne wywołania webhooka działają w czatach, ale tylko wtedy, gdy wszyscy użytkownicy mają włączone aplikacje do obsługi czatu. Nie możesz publikować webhooków w Google Workspace Marketplace.
Ten diagram przedstawia architekturę webhooka połączonego z Chatem:
Na poprzednim diagramie aplikacja Google Chat przesyła taki przepływ informacji:
- Logika aplikacji Chat otrzymuje informacje z zewnętrznych usług innych firm, takich jak system zarządzania projektami czy narzędzie do obsługi zgłoszeń.
- Logika aplikacji Google Chat jest hostowana w chmurze lub systemie lokalnym, który może wysyłać wiadomości za pomocą adresu URL webhooka do określonego pokoju czatu.
- Użytkownicy mogą odbierać wiadomości z aplikacji Google Chat w tym konkretnym pokoju czatu, ale nie mogą korzystać z aplikacji Google Chat.
Wymagania wstępne
Python
- Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat. Twoja organizacja Google Workspace musi umożliwić użytkownikom dodawanie i używanie przychodzących webhooków.
- Python 3.6 lub nowszy
- Narzędzie do zarządzania pakietami pip
Biblioteka
httplib2
. Aby zainstalować bibliotekę, uruchom w interfejsie wiersza poleceń to polecenie:pip install httplib2
Pokój Google Chat. Aby utworzyć pokój za pomocą interfejsu Google Chat API, zapoznaj się z artykułem Tworzenie pokoju. Aby je utworzyć w Google Chat, zapoznaj się z dokumentacją w Centrum pomocy.
Node.js
- Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat. Organizacja Google Workspace musi zezwalać użytkownikom na dodawanie i używanie przychodzących webhooków.
- Node.js w wersji 14 lub nowszej
- Narzędzie do zarządzania pakietami npm
- Pokój Google Chat. Aby utworzyć pokój za pomocą interfejsu Google Chat API, zapoznaj się z artykułem Tworzenie pokoju. Aby je utworzyć w Google Chat, zapoznaj się z dokumentacją w Centrum pomocy.
Java
- konto Google Workspace Business lub Enterprise z dostępem do Google Chat. Twoja organizacja Google Workspace musi umożliwić użytkownikom dodawanie i używanie przychodzących webhooków.
- Java 11 lub nowsza
- Narzędzie do zarządzania pakietami Maven
- Pokój Google Chat. Aby utworzyć pokój za pomocą interfejsu Google Chat API, zapoznaj się z artykułem Tworzenie pokoju. Aby je utworzyć w Google Chat, zapoznaj się z dokumentacją w Centrum pomocy.
Google Apps Script
- konto Google Workspace Business lub Enterprise z dostępem do Google Chat. Organizacja Google Workspace musi zezwalać użytkownikom na dodawanie i używanie przychodzących webhooków.
- Utwórz samodzielny projekt Apps Script i włącz zaawansowaną usługę czatu.
- Pokój Google Chat. Aby utworzyć pokój za pomocą interfejsu Google Chat API, zapoznaj się z artykułem Tworzenie pokoju. Aby je utworzyć w Google Chat, zapoznaj się z dokumentacją w Centrum pomocy.
Utwórz webhooka
Aby utworzyć webhooka, zarejestruj go w pokoju czatu, w którym chcesz otrzymywać wiadomości, a potem napisz skrypt, który wysyła wiadomości.
Rejestrowanie przychodzącego webhooka
- W przeglądarce otwórz Google Chat. Webhooków nie można konfigurować w aplikacji mobilnej Google Chat.
- Otwórz pokój, do którego chcesz dodać webhook.
- Obok tytułu pokoju kliknij strzałkę , aby rozwinąć więcej opcji, a następnie kliknij Aplikacje i integracje.
Kliknij
Dodaj webhooki.W polu Nazwa wpisz
Quickstart Webhook
.W polu URL awatara wpisz
https://developers.google.com/chat/images/chat-product-icon.png
.Kliknij Zapisz.
Aby skopiować adres URL webhooka, kliknij
Więcej, a następnie Kopiuj link.
Pisanie skryptu webhooka
Przykładowy skrypt webhooka wysyła wiadomość do pokoju, w którym webhook został zarejestrowany, przez wysłanie żądania POST
na jego adres URL. Interfejs Chat API odpowiada instancji Message
.
Wybierz język, aby dowiedzieć się, jak utworzyć skrypt webhooka:
Python
W katalogu roboczym utwórz plik o nazwie
quickstart.py
.W pliku
quickstart.py
wklej ten kod:Zastąp wartość zmiennej
url
adresem URL webhooka skopiowanym podczas rejestracji webhooka.
Node.js
W katalogu roboczym utwórz plik o nazwie
index.js
.W pliku
index.js
wklej ten kod:Zastąp wartość zmiennej
url
adresem URL webhooka skopiowanym podczas rejestracji webhooka.
Java
W katalogu roboczym utwórz plik o nazwie
pom.xml
.W narzędziu
pom.xml
skopiuj i wklej ten kod:W katalogu roboczym utwórz tę strukturę katalogów:
src/main/java
.W katalogu
src/main/java
utwórz plik o nazwieApp.java
.W aplikacji
App.java
wklej ten kod:Zastąp wartość zmiennej
URL
adresem URL webhooka, który został skopiowany podczas rejestracji webhooka.
Google Apps Script
W przeglądarce otwórz Apps Script.
Kliknij New Project (Nowy projekt).
Wklej ten kod:
Zastąp wartość zmiennej
url
adresem URL webhooka, który został skopiowany podczas rejestracji webhooka.
Uruchamianie skryptu webhooka
Uruchom skrypt w interfejsie wiersza poleceń:
Python
python3 quickstart.py
Node.js
node index.js
Java
mvn compile exec:java -Dexec.mainClass=App
Google Apps Script
- Kliknij Wykonaj.
Gdy uruchomisz kod, webhook wyśle wiadomość do pokoju, w którym go zarejestrowano.
Rozpocznij wątek wiadomości lub odpowiedz na niego
W treści żądania wiadomości podaj wartość
spaces.messages.thread.threadKey
. W zależności od tego, czy rozpoczynasz wątek, czy na niego odpowiadasz, użyj jednej z tych wartości w poluthreadKey
:Jeśli rozpoczynasz wątek, ustaw wartość
threadKey
na dowolny ciąg znaków, ale zanotuj tę wartość, aby opublikować odpowiedź na wątek.W przypadku odpowiadania w wątku podaj właściwość
threadKey
, która została ustawiona, gdy wątek się zaczynał. Aby na przykład opublikować odpowiedź w wątku, w którym pierwsza wiadomość zawierałaMY-THREAD
, ustawMY-THREAD
.
Zdefiniuj zachowanie wątku, jeśli określony element
threadKey
nie zostanie znaleziony:Odpowiedz w wątku lub zacznij nowy wątek. Do adresu URL webhooka dodaj parametr
messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD
. Przekazanie tego parametru adresu URL powoduje, że Google Chat wyszukuje istniejący wątek przy użyciu określonego parametruthreadKey
. Jeśli zostanie znaleziona, wiadomość zostanie opublikowany jako odpowiedź w tym wątku. Jeśli nie zostanie znaleziony, wiadomość rozpocznie nowy wątek odpowiadający temu zapytaniuthreadKey
.Odpowiedz w wątku lub nie rób nic. Dodaj parametr
messageReplyOption=REPLY_MESSAGE_OR_FAIL
do adresu URL webhooka. Przekazanie tego parametru adresu URL powoduje, że Google Chat wyszukuje istniejący wątek przy użyciu określonego parametruthreadKey
. Jeśli zostanie znaleziony, wiadomość zostanie opublikowana jako odpowiedź w tym wątku. Jeśli nie znaleziono żadnego, wiadomość nie została wysłana.
Więcej informacji znajdziesz w artykule
messageReplyOption
.
Ten przykładowy kod rozpoczyna się w wątku wiadomości lub odpowiada na nie:
Python
Node.js
Google Apps Script
Obsługa błędów
Żądania webhooka mogą się nie powieść z różnych powodów, m.in.:
- Nieprawidłowe żądanie.
- Webhook lub pokój, w którym się znajduje, został usunięty.
- Przejściowe problemy, takie jak brak połączenia sieciowego czy limity.
Podczas tworzenia webhooka należy odpowiednio obsługiwać błędy:
- Logowanie błędu.
- W przypadku błędów związanych z czasem, limitem lub połączeniem sieciowym ponownie wysyłaj żądanie ze wzrastającym czasem do ponowienia.
- Nic nie robić, co jest odpowiednie w przypadku wysyłania wiadomości webhooka.
Interfejs API Google Chat zwraca błędy jako google.rpc.Status
,
co obejmuje błąd HTTP code
, który wskazuje typ błędu: błąd klienta (seria 400) lub błąd serwera (seria 500). Aby przejrzeć wszystkie mapowania HTTP, otwórz google.rpc.Code
.
{
"code": 503,
"message": "The service is currently unavailable.",
"status": "UNAVAILABLE"
}
Aby dowiedzieć się, jak interpretować kody stanu HTTP i jak obsługiwać błędy, zapoznaj się z artykułem Błędy.
Ograniczenia i uwagi
- Gdy tworzysz wiadomość za pomocą webhooka w Google Chat API, odpowiedź nie zawiera pełnej wiadomości.
Odpowiedź zawiera tylko pola
name
ithread.name
.
Powiązane artykuły
- Wybieranie architektury aplikacji Google Chat
- Wysyłanie wiadomości na karcie
- Formatowanie wiadomości