Praca z wydarzeniami z Google Chat

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

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

Oto kilka przykładów wykorzystania zdarzeń:

• monitorować nowe wiadomości w pokoju i odpowiadać na nie, np. sprawdzać, czy zawierają słowa kluczowe lub wyrażenia;
• Wysyłaj wiadomość powitalną do użytkowników, gdy dołączają do pokoju, aby wyjaśnić im zasady obowiązujące w pokoju lub udostępnić wskazówki dotyczące efektywnego korzystania z aplikacji Google Chat.
• śledzenie i analizowanie aktywności w Google Chat; Możesz na przykład wysyłać miesięczny raport o nowych członkach społeczności lub wiadomościach, które wywołują najwięcej reakcji lub odpowiedzi.
• Komunikuj 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ą wydarzenia

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

Google Chat kategoryzuje zdarzenia 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 pokazano, jak aktywność w Google Chat wpływa na powiązany zasób interfejsu Chat API oraz jaki typ zdarzenia otrzymuje aplikacja do Google Chat:

Aktywność	Zasób interfejsu Chat API	Typ zdarzenia
Użytkownik publikuje wiadomość w pokoju czatu	Zostanie utworzony zasób Message.	Nowa wiadomość
Użytkownik staje się menedżerem pokoju.	Zasób Membership został zaktualizowany.	Zaktualizowano subskrypcję
Użytkownik reaguje na wiadomość.	Zostanie utworzony zasób Reaction.	Nowa reakcja
użytkownik opuszcza pokój;	Zasób Membership został usunięty.	Usunięto subskrypcję

Odbieranie zdarzeń z Google Chat

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

• Subskrybuj zdarzenia za pomocą interfejsu Google Workspace Events API, aby otrzymywać informacje o zdarzeniach, gdy tylko wystąpią.
• Wysyłanie zapytania o ostatnie zdarzenia przez wywołanie interfejsu Chat API.

W tabeli poniżej wyjaśniono różnice między wysyłaniem zapytań o zdarzenia a subskrybowaniem zdarzeń oraz powody, dla których warto korzystać z tych funkcji:

	Subskrybowanie zdarzeń	Zapytanie o zdarzenia
Przypadki użycia	Przetwarzaj zdarzenia lub reaguj na nie w czasie rzeczywistym. Monitoruj aktywność użytkowników związaną z członkostwem i odkrywaj nowe pokoje do monitorowania.	Przetwarzaj zdarzenia lub reaguj na nie okresowo albo za pomocą aktywatora. Pobieranie pominiętych zdarzeń z subskrypcji (z powodu przerwy w działaniu lub nieaktywnej subskrypcji).
Interfejs API	Interfejs Google Workspace Events API	Chat API
Źródło zdarzeń	pokoje, użytkownicy i organizacje Google Workspace (science 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 zasobie spaceEvents w dokumentacji interfejsu Chat API.
Format zdarzenia	Wiadomość Google Cloud Pub/Sub sformatowana zgodnie ze specyfikacją CloudEvent. Szczegółowe informacje znajdziesz w artykule Struktura zdarzeń Google Workspace.	Zasób interfejsu Chat API ( spaces.spaceEvent)
Dane zdarzeń	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ń zawierają tylko określone pola zasobów. Przykładowe ładunki znajdziesz w dokumentacji.

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

W tym przykładzie aplikacja Google Chat chce otrzymywać informacje o zmianach dotyczących użytkowników pokoju czatu. W pokoju mają miejsce te działania związane z członkostwem:

• Użytkownik dołącza do pokoju, co powoduje utworzenie zasobu Membership i wywołanie zdarzenia Nowy członek społeczności.
• Użytkownik zostaje menedżerem pokoju, co powoduje zaktualizowanie zasobu Membership dla użytkownika i wywołanie zdarzenia zaktualizowania użytkownika.
• Użytkownik opuszcza pokój, co powoduje usunięcie zasobu Membership dla użytkownika i wywołanie zdarzenia usunięcia użytkownika.

Subskrybowanie zdarzeń dotyczących członkostwa

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 użytkownikami. Po utworzeniu subskrypcji aplikacja Google Chat może zacząć otrzymywać zdarzenia dotyczące członkostwa.

Na rysunku 2 aplikacja do obsługi czatu ma aktywną subskrypcję pokoju, więc otrzymuje zdarzenie za każdym razem, gdy zmienia się stan członkostwa w pokoju. Aplikacja do Google Chat może następnie przetwarzać te działania lub reagować na nie w czasie rzeczywistym, na przykład wysyłając prywatną wiadomość powitalną do użytkownika, który dołączył do pokoju.

Aby dowiedzieć się, jak tworzyć subskrypcje za pomocą interfejsu Google Workspace Events API, zapoznaj się z dokumentacją 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 Google Chat może wywołać interfejs Chat API, aby wyświetlić listę ostatnich zdarzeń w pokoju związanych z aktywnością członków.

Na rysunku 3 aplikacja do Google Chat wywołuje metodę spaces.spaceEvents.list() interfejsu Chat API 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 do Google Chat może następnie przetworzyć te informacje lub odpowiedzieć na podstawie ostatniej aktywności, np. opublikować cotygodniową wiadomość z podsumowaniem aktywności użytkownikó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 Google Chat.

Ograniczenia i sposoby wyświetlania

Ograniczenia ogólne

• Aby otrzymywać zdarzenia dotyczące subskrypcji, użytkownik lub aplikacja Google Chat musi być bezpośrednim użytkownikiem pokoju. Jeśli zostali dodani, zaktualizowani lub usunięci pośrednio z pokoju za pomocą grupy dyskusyjnej Google, subskrypcja nie otrzymuje tych zdarzeń dotyczących członkostwa. Aby dowiedzieć się, jak działa członkostwo w grupach dyskusyjnych Google, przeczytaj artykuł Dodawanie grupy dyskusyjnej Google do pokoju.

Subskrypcje użytkownika

• W przypadku subskrypcji użytkowników zdarzenia dotyczące nowych członków społeczności w czatach lub czatach grupowych bez nazwy (google.workspace.chat.membership.v1.created) są wywoływane dopiero po opublikowaniu pierwszej wiadomości.

Subskrypcje klientów

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

• Organizacja Google Workspace musi mieć co najmniej 1 licencję SKU Enterprise.
• Aplikacja Google Chat może utworzyć tylko jedną subskrypcję klienta dla danej organizacji Google Workspace. Organizacja Google Workspace może mieć łącznie do 5 subskrypcji klientów (utworzonych przez różne aplikacje do Google Chat).

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

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

Jedynym wyjątkiem od tych zasad są wydarzenia związane z subskrypcją. Twoja subskrypcja może otrzymywać zdarzenia dotyczące użytkowników 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 w pokoju zarządzanym przez organizację Google Workspace nastąpi zmiana członkostwa, zostanie ona dostarczona jako zdarzenie w pokoju.

Nazwa zasobu zdarzenia dotyczącego 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 pokoju zewnętrznym lub na czacie utworzonym przez użytkownika zewnętrznego), Twoja subskrypcja otrzyma to zdarzenie jako zdarzenie użytkownika.

Nazwa zasobu zdarzenia użytkownika ma taki format:

users/{userId}/userEvents/{userEventId}

Powiązane artykuły

• Omówienie interfejsu Google Workspace Events API
• Tworzenie subskrypcji
• Uzyskiwanie szczegółowych informacji o zdarzeniu w pokoju Google Chat
• Wyświetlanie listy zdarzeń z pokoju Google Chat