Praca z wydarzeniami z Google Chat

Na tej stronie dowiesz się, jak aplikacje Google Chat mogą odbierać 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 zrozumieć, 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ści powitalne, 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

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 Chat o rodzaju aktywności, która wystąpiła, 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 w 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
  • Przetwarzaj zdarzenia i reaguj na nie w czasie rzeczywistym.
  • Monitoruj aktywność użytkowników związaną z członkostwem i odkrywaj nowe pokoje do monitorowania.
  • Przetwarzanie zdarzeń lub odpowiadanie 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ń Przestrzenie, użytkownicy i organizacje Google Workspace ( wersja przedpremierowa dla programistów) 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 w dokumentacji referencyjnej 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 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 użytkowników pokoju w Google Chat. W pokoju następuje następująca aktywność związana 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 użytkownika i wywołuje zaktualizowane zdarzenie dotyczące uczestnika.
  • Użytkownik opuszcza przestrzeń, co powoduje usunięcie zasobu Membership dla tego 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 do obsługi czatu wywołuje metodę subscriptions.create() interfejsu Google Workspace Events API, aby subskrybować pokój 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 osób w pokojach w ramach subskrypcji za pomocą interfejsu Google Workspace Events API.

Na ilustracji 2 aplikacja do obsługi czatu 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. A Aplikacja do obsługi czatu otrzymuje ostatnie zdarzenia związane z członkostwem, wysyłając zapytania o zdarzenia w pokoju za pomocą interfejsu Chat API.

Na ilustracji 3 aplikacja Google Chat wywołuje metodę interfejsu 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ń 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 i sposoby dostarczania

Ograniczenia ogólne

  • Aby otrzymywać zdarzenia dotyczące członkostwa, użytkownik lub aplikacja 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 otrzyma tych zdarzeń związanych z członkostwem. Więcej informacji o członkostwie w grupach dyskusyjnych Google znajdziesz w artykule Dodawanie grupy dyskusyjnej Google do pokoju.

Subskrypcje użytkownika

  • 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.

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ę SKU Enterprise. Pamiętaj, że to wymaganie nie jest ściśle egzekwowane na etapie programu wczesnego dostępu dla deweloperów, ale będzie egzekwowane w przyszłości (o czym poinformujemy osobno).
  • Aplikacja do obsługi czatu może utworzyć tylko 1 subskrypcję klienta w danej organizacji Google Workspace. Organizacja Google Workspace może mieć łącznie maksymalnie 5 subskrypcji klientów (utworzonych przez różne aplikacje do obsługi czatu).

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

  • Wydarzenia na czacie: dostarczane tylko wtedy, gdy wydarzenie ma miejsce na czacie zarządzanym przez Twoją organizację korzystającą z Google Workspace.
  • Wydarzenia użytkownika: dostarczane tylko wtedy, gdy wydarzenie dotyczy użytkownika należącego do Twojej organizacji Google Workspace.

Jedynym wyjątkiem od tych zasad są wydarzenia dla wspierających. Subskrypcja może otrzymywać zdarzenia dotyczące członkostwa zarówno w pokojach zarządzanych przez Twoją organizację, jak i w pokojach zarządzanych przez organizacje zewnętrzne, ale sposób ich dostarczania zależy od tego, która organizacja zarządza pokojem:

Przestrzenie zarządzane przez organizację Google Workspace

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

Nazwa zasobu zdarzenia dotyczącego przestrzeni ma ten format:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Pokoje zarządzane przez organizacje zewnętrzne

Jeśli w pokoju zarządzanym przez organizację zewnętrzną (np. w zewnętrznym pokoju z nazwą lub na czacie utworzonym przez użytkownika zewnętrznego) zmieni się członkostwo użytkownika zarządzanego przez Twoją organizację Google Workspace, Twoja subskrypcja otrzyma to zdarzenie jako zdarzenie użytkownika.

Nazwa zasobu zdarzenia użytkownika ma ten format:

users/{userId}/userEvents/{userEventId}