Praca z wydarzeniami z Google Chat

Z tej strony dowiesz się, jak aplikacje Google Chat mogą odbierać zdarzenia w Google Chat i na nie reagować.

Zdarzenie Google Chat to aktywność lub zmiana w Google Chat, np. nowa wiadomość w pokoju. Aplikacja 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 użycia zdarzeń:

  • Monitorowanie nowych wiadomości w pokoju i reagowanie na nie, np. sprawdzanie, czy zawierają słowa kluczowe lub frazy.
  • Wysyłanie wiadomości powitalnej do użytkowników, którzy dołączają do pokoju, aby wyjaśnić zasady dotyczące pokoju lub udostępnić wskazówki dotyczące skutecznego korzystania z aplikacji Google Chat.
  • Śledzenie i analizowanie aktywności w Google Chat. Możesz na przykład wysyłać co miesiąc raport o nowych użytkownikach lub wiadomościach, które otrzymują najwięcej reakcji lub odpowiedzi.
  • Komunikowanie 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 na innej platformie do obsługi wiadomości bez opuszczania Google Chat.

Jak działają zdarzenia

Gdy w Google Chat coś się dzieje, zasób Google Chat API jest tworzony, aktualizowany lub usuwany. Google Chat używa zdarzeń, aby przekazywać do aplikacji Google Chat informacje o typie aktywności, która wystąpiła, oraz o zasobie Google 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 Google Chat, co powoduje utworzenie zasobu Message. Google Chat tworzy wtedy zdarzenie zawierające dane o nowej wiadomości.

Google Chat dzieli zdarzenia na kategorie według typu. Typy zdarzeń pomagają filtrować i otrzymywać tylko te informacje, których potrzebujesz, oraz umożliwiają obsługę podobnych działań w ten sam sposób.

W tabeli poniżej pokazujemy, jak aktywność w Google Chat wpływa na powiązany zasób Google Chat API oraz jaki typ zdarzenia otrzymuje aplikacja Google Chat:

Aktywność Zasób Google Chat API Typ zdarzenia
Użytkownik publikuje wiadomość w pokoju Google Chat. Tworzony jest zasób Message. Nowa wiadomość
Użytkownik staje się menedżerem pokoju. Aktualizowany jest zasób Membership. Zaktualizowane członkostwo
Użytkownik reaguje na wiadomość. Tworzony jest zasób Reaction. Nowa reakcja
Użytkownik opuszcza pokój. Usuwany jest zasób Membership. Usunięte członkostwo

Otrzymywanie zdarzeń z Google Chat

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

  • Subskrybować zdarzenia za pomocą interfejsu Google Workspace Events API, aby otrzymywać zdarzenia w miarę ich występowania.
  • Wysyłać zapytania o ostatnie zdarzenia, wywołując Google Chat API.

W tabeli poniżej wyjaśniamy różnicę między wysyłaniem zapytań o zdarzenia a subskrybowaniem ich oraz powody, dla których warto to robić:

Subskrybuj zdarzenia Wysyłaj zapytania o zdarzenia
Przypadki użycia
  • Przetwarzaj zdarzenia lub reaguj na nie w czasie rzeczywistym.
  • Monitoruj aktywność użytkowników w zakresie członkostwa i odkrywaj nowe pokoje do monitorowania.
  • Przetwarzaj zdarzenia lub reaguj na nie okresowo albo za pomocą aktywatora.
  • Pobieraj pominięte zdarzenia z subskrypcji (z powodu awarii lub nieaktywnej subskrypcji).
Interfejs API Google Workspace Events API Google Chat API
Źródło zdarzeń Pokoje, użytkownicy i organizacje Google Workspace ( wersja przedpremierowa dla programistów) Tylko pokoje
Obsługiwane zdarzenia
  • Wiadomości
  • Członkostwo
  • Reakcje
  • Spacja

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

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

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

W tym przykładzie aplikacja Google Chat chce otrzymywać informacje o zmianach dotyczących użytkowników pokoju Google Chat. W pokoju występuje ta aktywność związana z członkostwem:

  • Użytkownik dołącza do pokoju, co powoduje utworzenie zasobu Membership i wywołanie zdarzenia nowego użytkownika.
  • Użytkownik staje się menedżerem pokoju, co powoduje zaktualizowanie zasobu Membership dla tego użytkownika i wywołanie zdarzenia zaktualizowanego użytkownika.
  • Użytkownik opuszcza pokój, co powoduje usunięcie zasobu Membership dla tego użytkownika i wywołanie zdarzenia usuniętego użytkownika.

Subskrybowanie zdarzeń dotyczących członkostwa

Aby otrzymywać zdarzenia w czasie rzeczywistym, aplikacja Google Chat wywołuje metodę interfejsu Google Workspace Events APIsubscriptions.create(), aby subskrybować pokój pod kątem wszystkich typów zdarzeń dotyczących członkostwa. Po utworzeniu subskrypcji aplikacja Google Chat może zacząć otrzymywać zdarzenia dotyczące członkostwa.

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

Na rysunku 2 aplikacja Google Chat ma aktywną subskrypcję pokoju, więc otrzymuje zdarzenie za każdym razem, gdy zmienia się członkostwo w pokoju. Aplikacja Google Chat może wtedy przetwarzać lub odpowiadać w czasie rzeczywistym na dowolne działania, np. wysyłać prywatną wiadomość powitalną do użytkownika, 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.

Wysyłanie zapytań o ostatnie zdarzenia dotyczące członkostwa

Zamiast otrzymywać zdarzenia dotyczące członkostwa w miarę ich występowania, aplikacja Google Chat może wywołać Google 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 Google Chat otrzymuje ostatnie zdarzenia dotyczące członkostwa, wysyłając zapytania o zdarzenia w pokoju za pomocą Google Chat API.

Na rysunku 3 aplikacja Google Chat wywołuje metodę Google Chat API spaces.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ń dotyczących członkostwa. Google Chat API zwraca listę zasobów spaceEvent, które reprezentują każdą zmianę członkostwa. Aplikacja Google Chat może wtedy przetwarzać lub odpowiadać na podstawie ostatniej aktywności, np. publikować co tydzień wiadomość z podsumowaniem aktywności związanej z członkostwem w pokoju w ciągu ostatnich 7 dni.

Aby wysyłać zapytania o zdarzenia za pomocą Google Chat API, przeczytaj artykuł Wyświetlanie listy zdarzeń z pokoju Google Chat.

Ograniczenia i zachowania związane z dostarczaniem

Ograniczenia ogólne

  • Aby otrzymywać zdarzenia dotyczące członkostwa, użytkownik lub aplikacja Google Chat musi być bezpośrednim członkiem pokoju. Jeśli użytkownik został dodany, zaktualizowany lub usunięty z pokoju pośrednio za pomocą grupy dyskusyjnej Google, subskrypcja nie będzie otrzymywać tych zdarzeń dotyczących członkostwa. Aby dowiedzieć się, jak działa członkostwo w grupie dyskusyjnej Google, przeczytaj artykuł Dodawanie grupy dyskusyjnej Google do pokoju.

Subskrypcje użytkownika

  • W przypadku subskrypcji użytkowników zdarzenia dotyczące nowych użytkowników w wiadomościach bezpośrednich lub nienazwanych czatach grupowych (google.workspace.chat.membership.v1.created), są wywoływane dopiero po opublikowaniu pierwszej wiadomości.

Subskrypcje klientów ( wersja przedpremierowa dla programistów)

W przypadku subskrypcji klientów obowiązują te ograniczenia:

  • Organizacja Google Workspace musi mieć co najmniej 1 licencję na jednostkę SKU Enterprise. Pamiętaj, że ten wymóg nie jest ściśle egzekwowany na etapie programu w wersji przedpremierowej dla deweloperów, ale będzie egzekwowany w przyszłości (informacje zostaną podane osobno).
  • Aplikacja Google Chat może utworzyć tylko 1 subskrypcję klienta dla danej organizacji Google Workspace. Organizacja Google Workspace może mieć maksymalnie 5 subskrypcji klientów (utworzonych przez różne aplikacje Google Chat).

W przypadku subskrypcji klientów dostarczanie zdarzeń podlega tym ogólnym regułom:

  • Zdarzenia w pokoju: są dostarczane tylko wtedy, gdy zdarzenie wystąpi w pokoju zarządzanym przez Twoją organizację Google Workspace.
  • Zdarzenia użytkownika: są dostarczane tylko wtedy, gdy zdarzenie wystąpi w przypadku użytkownika należącego do Twojej organizacji Google Workspace.

Jedynym wyjątkiem od tych reguł są zdarzenia dotyczące członkostwa. Twoja subskrypcja może otrzymywać zdarzenia dotyczące członkostwa zarówno z pokoi zarządzanych przez Twoją organizację, jak i z pokoi zarządzanych przez organizacje zewnętrzne, ale sposób ich dostarczania zależy od tego, która organizacja zarządza pokojem:

Pokoje zarządzane przez Twoją organizację Google Workspace

Jeśli zmiana członkostwa nastąpi w pokoju zarządzanym przez organizację Google Workspace, zostanie ona dostarczona jako zdarzenie w pokoju.

Nazwa zasobu zdarzenia w pokoju ma ten format:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Pokoje zarządzane przez organizacje zewnętrzne

Jeśli członkostwo użytkownika zarządzanego przez Twoją organizację Google Workspace zmieni się w pokoju zarządzanym przez organizację zewnętrzną (np. w zewnętrznym pokoju nazwanym lub w wiadomości bezpośredniej utworzonej przez użytkownika zewnętrznego), Twoja subskrypcja otrzyma to zdarzenie jako zdarzenie użytkownika.

Nazwa zasobu zdarzenia użytkownika ma ten format:

users/{userId}/userEvents/{userEventId}