Praca z wydarzeniami z Google Chat

Na tej stronie dowiesz się, jak aplikacje Google Chat mogą otrzymywać zdarzenia w Google Chat i na nie odpowiadać.

Wydarzenie w Google Chat reprezentuje aktywność lub zmianę w Chat, np. nową wiadomość w pokoju. Aplikacja w Google Chat może używać zdarzeń, aby dowiedzieć się, co się stało, i podjąć działania lub odpowiedzieć w sposób, który będzie przydatny dla użytkowników.

Oto kilka przykładów zastosowań zdarzeń:

  • monitorować nowe wiadomości w pokoju i na nie odpowiadać, np. sprawdzać, czy zawierają kluczowe słowa lub frazy;
  • Wysyłaj do użytkowników wiadomość powitalną, gdy dołączają do pokoju, aby wyjaśnić zasady pokoju lub podzielić się wskazówkami dotyczącymi skutecznego korzystania z aplikacji Chat.
  • śledzić i analizować aktywność w Google Chat; Możesz na przykład wysyłać miesięczny raport o nowych wspierających lub wiadomościach, które uzyskują najwięcej reakcji lub odpowiedzi.
  • komunikować się na różnych platformach do obsługi wiadomości, Użytkownicy mogą na przykład wysyłać i odbierać wiadomości od użytkowników innej platformy do obsługi wiadomości bez opuszczania Google Chat.

Jak działają zdarzenia

Za każdym razem, gdy w Google Chat coś się dzieje, zasób interfejsu Google Chat API jest tworzony, aktualizowany lub usuwany. Google Chat używa zdarzeń do przekazywania informacji do aplikacji Google Chat o rodzaju aktywności i zasobie interfejsu Chat API, którego dotyczy.

Przykład tego, jak wiadomość opublikowana w pokoju Google Chat wywołuje zdarzenie.
Rysunek 1. Użytkownik publikuje wiadomość w pokoju czatu, co powoduje utworzenie zasobu Message. Chat tworzy wtedy zdarzenie zawierające dane o nowej wiadomości.

Chat kategoryzuje zdarzenia według typu. Typy zdarzeń pomagają filtrować i otrzymywać tylko potrzebne informacje oraz umożliwiają podobne działania w ten sam sposób.

W tabeli poniżej pokazano, jak aktywność w Google Chat wpływa na powiązane zasoby interfejsu Chat API oraz jaki typ zdarzenia otrzymuje aplikacja do obsługi Google Chat:

Aktywność Zasób Chat API Typ zdarzenia
Użytkownik publikuje wiadomość w pokoju Google Chat Utworzono zasób Message. Nowa wiadomość
Użytkownik staje się menedżerem pokoju. Zasób Membership jest aktualizowany. Zaktualizowano poziom wspierania
Użytkownik reaguje na wiadomość. Utworzono zasób Reaction. Nowa reakcja
użytkownik opuści pokój. Zasób Membership zostanie usunięty. Usunięto wspieranie

Odbieranie zdarzeń z Google Chat

Aby otrzymywać zdarzenia, aplikacja Google Chat może wykonać jedną z tych czynności:

  • Subskrybuj zdarzenia za pomocą interfejsu Google Workspace Events API, aby otrzymywać zdarzenia na bieżąco.
  • Wysyłaj zapytania o ostatnie zdarzenia, wywołując interfejs Chat API.

W tabeli poniżej znajdziesz wyjaśnienie różnic między wysyłaniem zapytań o zdarzenia a subskrybowaniem zdarzeń oraz przyczyny tych różnic:

Subskrybowanie zdarzeń Zapytanie o zdarzenia
Przypadki użycia
  • przetwarzać zdarzenia i na nie odpowiadać w czasie rzeczywistym;
  • Monitoruj aktywność użytkowników związaną z członkostwem i odkrywaj nowe pokoje do monitorowania.
  • przetwarzać zdarzenia lub odpowiadać na nie okresowo lub za pomocą aktywatora;
  • Pobieranie pominiętych zdarzeń z subskrypcji (z powodu awarii lub nieaktywnej subskrypcji).
Interfejs API Interfejs Google Workspace Events API Chat API
Źródło zdarzeń Pokoje i użytkownicy Tylko pokoje
Obsługiwane zdarzenia
  • Wiadomości
  • Wspieranie kanału
  • Reakcje
  • Spacja

Listę obsługiwanych typów zdarzeń znajdziesz w artykule Typy zdarzeń do tworzenia subskrypcji w dokumentacji interfejsu Google Workspace Events API.
  • Wiadomości
  • Wspieranie kanału
  • Reakcje
  • Spacja

Listę obsługiwanych typów zdarzeń znajdziesz w spaceEvents dokumentacji interfejsu Chat API.
Format zdarzenia Wiadomość Google Cloud Pub/Sub sformatowana zgodnie ze specyfikacją CloudEvent. Więcej informacji znajdziesz w artykule Struktura zdarzeń Google Workspace. Zasób interfejsu Chat API ( spaces.spaceEvent)
Dane zdarzenia Ciąg tekstowy zakodowany w formacie Base64 z danymi zasobu lub bez nich. Przykładowe ładunki znajdziesz w sekcji Dane zdarzenia. Ładunek JSON zawierający dane zasobu. Niektóre typy zdarzeń obejmują tylko określone pola zasobów. Przykładowe ładunki znajdziesz w dokumentacji.

Przykład: wysyłanie zapytań o wydarzenia dotyczące członkostwa w pokoju lub subskrybowanie takich wydarzeń

W tym przykładzie aplikacja Google Chat chce otrzymywać informacje o zmianach dotyczących uczestników pokoju w Google Chat. W pokoju wystąpią następujące działania związane z członkostwem:

  • Użytkownik dołącza do pokoju, co powoduje utworzenie zasobu Membership i wywołanie zdarzenia nowego uczestnika.
  • Użytkownik staje się menedżerem pokoju, co powoduje aktualizację zasobu Membership dla użytkownika i wywołuje zaktualizowane zdarzenie dotyczące uczestnika.
  • Użytkownik opuszcza przestrzeń, co powoduje usunięcie zasobu Membership dla użytkownika i wywołuje zdarzenie usunięcia członka.

Subskrybowanie zdarzeń związanych ze wspieraniem kanału

Aby otrzymywać zdarzenia w czasie rzeczywistym, aplikacja Chat wywołuje metodę interfejsu Google Workspace Events API subscriptions.create() w celu subskrybowania pokoju w przypadku wszystkich typów zdarzeń związanych z członkostwem. Po utworzeniu subskrypcji aplikacja Chat może zacząć odbierać zdarzenia dotyczące członkostwa.

aplikacja do obsługi czatu, która subskrybuje zdarzenia za pomocą interfejsu Google Workspace Events API;
Rysunek 2. Aplikacja w Chat otrzymuje zdarzenia dotyczące członkostwa w ramach subskrypcji za pomocą interfejsu Google Workspace Events API.

Na ilustracji 2 aplikacja Google Chat ma aktywną subskrypcję pokoju, więc otrzymuje zdarzenie za każdym razem, gdy zmienia się członkostwo w pokoju. Aplikacja Chat może wtedy przetwarzać lub odpowiadać w czasie rzeczywistym na dowolne działania, takie jak wysyłanie prywatnej wiadomości powitalnej do członka, który dołączył do pokoju.

Więcej informacji o tworzeniu subskrypcji za pomocą interfejsu Google Workspace Events API znajdziesz w dokumentacji interfejsu Google Workspace Events API.

Zapytanie o ostatnie zdarzenia związane z członkostwem

Zamiast otrzymywać zdarzenia dotyczące członkostwa w miarę ich występowania, aplikacja do obsługi czatu może wywołać interfejs Chat API, aby wyświetlić listę ostatnich zdarzeń w pokoju związanych z aktywnością dotyczącą członkostwa.

Aplikacja do obsługi czatu, która wysyła zapytania o zdarzenia za pomocą interfejsu Chat API.
Rysunek 3. Aplikacja do obsługi czatu otrzymuje najnowsze zdarzenia związane z członkostwem, wysyłając zapytania o zdarzenia w pokoju za pomocą interfejsu Chat API.

Na ilustracji 3 aplikacja do obsługi czatu wywołuje metodę interfejsu Chat APIspaces.spaceEvents.list() po wystąpieniu wszystkich działań związanych z członkostwem i filtruje zapytanie pod kątem nowych, zaktualizowanych i usuniętych zdarzeń związanych z członkostwem. Interfejs Chat API zwraca listę zasobów spaceEvent, które reprezentują każdą zmianę członkostwa. Aplikacja Chat może wtedy przetwarzać informacje lub odpowiadać na podstawie ostatnich działań, np. publikować co tydzień wiadomość z podsumowaniem aktywności członków pokoju w ciągu ostatnich 7 dni.

Aby wysyłać zapytania o zdarzenia za pomocą interfejsu Chat API, zapoznaj się z artykułem Wyświetlanie listy zdarzeń z pokoju w Google Chat.

Ograniczenia
  • W przypadku subskrypcji użytkowników zdarzenia dotyczące nowych członków w wiadomościach bezpośrednich lub czatach grupowych bez nazwy (google.workspace.chat.membership.v1.created) są wywoływane dopiero po opublikowaniu pierwszej wiadomości.
  • Aby otrzymywać zdarzenia dotyczące członkostwa, użytkownik musi być bezpośrednim członkiem przestrzeni. Jeśli użytkownik został dodany, zaktualizowany lub usunięty z pokoju pośrednio za pomocą grupy dyskusyjnej Google, subskrypcja nie otrzyma tych zdarzeń związanych z członkostwem. Aby dowiedzieć się, jak działają członkostwa w grupach dyskusyjnych Google, zapoznaj się z artykułem Dodawanie grupy dyskusyjnej Google do pokoju.