Uwierzytelnianie i autoryzowanie aplikacji do obsługi czatu oraz żądań do interfejsu Google Chat API

Uwierzytelnianie i autoryzacja to mechanizmy używane odpowiednio do weryfikacji tożsamości i dostępu do zasobów. Ten dokument opisuje sposób uwierzytelniania i autoryzacji w przypadku aplikacji do obsługi czatu i żądań do interfejsu Chat API.

Omówienie procesu

Poniższy diagram przedstawia ogólne kroki uwierzytelniania i autoryzacji w Google Chat:

Ogólne instrukcje uwierzytelniania i autoryzacji w Google Chat
Rysunek 1. Ogólne instrukcje uwierzytelniania i autoryzacji w Google Chat.

  1. Skonfigurowanie projektu Google Cloud, włączenie Chat API i skonfigurowanie aplikacji Google Chat: w trakcie programowania tworzysz projekt Google Cloud. W projekcie Google Cloud możesz włączyć interfejs Chat API, skonfigurować aplikację Google Chat i skonfigurować uwierzytelnianie. Więcej informacji znajdziesz w artykułach na temat programowania w Google Workspace i tworzenia aplikacji do obsługi czatu.

  2. Call Chat API: gdy aplikacja wywołuje interfejs Chat API, wysyła do niego dane uwierzytelniające. Jeśli aplikacja uwierzytelnia się przy użyciu konta usługi, dane logowania są wysyłane jako część jej kodu. Jeśli Twoja aplikacja wymaga wywołania interfejsu Chat API przy użyciu uwierzytelniania użytkownika, które nie zostało jeszcze potwierdzone, prosi użytkownika o zalogowanie się.

  3. Żądanie zasobów: aplikacja prosi o dostęp w zakresach, które określasz podczas konfigurowania uwierzytelniania.

  4. Poproś o zgodę: jeśli Twoja aplikacja uwierzytelnia się jako użytkownik, Google wyświetla ekran zgody OAuth, aby użytkownik mógł zdecydować, czy zezwolić aplikacji na dostęp do żądanych danych. Uwierzytelnianie za pomocą konta usługi nie wymaga zgody użytkownika.

  5. Wyślij zatwierdzone żądanie zasobów: jeśli użytkownik wyrazi zgodę na zakresy autoryzacji, aplikacja dołączy do żądania dane logowania i zatwierdzone przez użytkownika zakresy. Żądanie jest wysyłane do serwera autoryzacji Google w celu uzyskania tokena dostępu.

  6. Google zwraca token dostępu: token dostępu zawiera listę udostępnionych zakresów. Jeśli zwrócona lista zakresów jest bardziej restrykcyjna niż te, których dotyczy żądanie, aplikacja wyłącza wszystkie funkcje ograniczone tokenem.

  7. Dostęp do żądanych zasobów: aplikacja używa tokena dostępu Google do wywoływania interfejsu Chat API i uzyskiwania dostępu do zasobów interfejsu Chat API.

  8. Uzyskaj token odświeżania (opcjonalnie): jeśli aplikacja musi mieć dostęp do interfejsu Google Chat API po upływie okresu ważności pojedynczego tokena dostępu, może otrzymać token odświeżania. Więcej informacji znajdziesz w artykule o dostępie do interfejsów API Google przy użyciu OAuth 2.0.

  9. Zgłaszanie prośby o więcej zasobów: jeśli aplikacja potrzebuje większego dostępu, prosi użytkownika o przyznanie nowych zakresów, co skutkuje nowym żądaniem uzyskania tokena dostępu (kroki 3–6).

Kiedy aplikacje do obsługi czatu wymagają uwierzytelnienia

Aplikacje do obsługi czatu mogą wysyłać wiadomości w odpowiedzi na interakcję użytkownika lub asynchronicznie. Mogą też wykonywać zadania w imieniu użytkownika, np. tworzyć pokoje czatu lub uzyskiwać listę osób w pokoju czatu.

Aplikacje do obsługi czatu nie wymagają uwierzytelniania do odpowiedzi na interakcję użytkownika, chyba że podczas przetwarzania odpowiedzi wywołają interfejs Chat API lub inny interfejs Google API.

Aby wysyłać asynchroniczne wiadomości lub wykonywać zadania w imieniu użytkownika, aplikacje do obsługi czatu wysyłają żądania REST do interfejsu Chat API, które wymagają uwierzytelniania i autoryzacji.

Odpowiedzi na interakcje użytkowników nie wymagają uwierzytelniania

Aplikacje Google Chat nie muszą uwierzytelniać się jako użytkownik ani jako aplikacja Google Chat, aby odbierać zdarzenia interakcji i odpowiadać na nie synchronicznie.

Aplikacje Google Chat odbierają zdarzenia interakcji za każdym razem, gdy użytkownik wchodzi w interakcję lub je wywołuje, na przykład:

  • Użytkownik wysyła wiadomość do aplikacji Google Chat.
  • Użytkownik dodaje @wzmiankę o aplikacji do obsługi czatu.
  • Użytkownik wywołuje jedno z poleceń po ukośniku w aplikacji Google Chat.

Poniższy diagram przedstawia sekwencję żądania-odpowiedź między użytkownikiem Google Chat a aplikacją Google Chat:

Zdarzenia interakcji z aplikacją Google Chat nie wymagają autoryzacji
Rysunek 2. Zdarzenia interakcji z aplikacją Google Chat nie wymagają uwierzytelniania.

  1. użytkownik wysyła wiadomość do aplikacji Google Chat w Google Chat.
  2. Google Chat przekaże wiadomość do aplikacji.
  3. Aplikacja odbiera wiadomość, przetwarza ją i zwraca odpowiedź do Google Chat.
  4. Google Chat renderuje odpowiedź w imieniu użytkownika lub w pokoju.

Ta sekwencja powtarza się w przypadku każdego zdarzenia interakcji z Google Chat.

Wiadomości asynchroniczne wymagają uwierzytelniania

Wiadomości asynchroniczne mają miejsce, gdy aplikacja do obsługi czatu wysyła żądanie do Chat API, który wymaga uwierzytelniania i autoryzacji.

Wywołując interfejs Chat API, aplikacje do obsługi czatu mogą publikować wiadomości w Google Chat, wykonywać zadania i uzyskiwać dostęp do danych w imieniu użytkownika. Na przykład po wykryciu przerwy w działaniu serwera aplikacja do obsługi czatu może wywołać interfejs Chat API, aby:

  • Utwórz pokój czatu przeznaczony do analizy i rozwiązywania problemów z przerwami w działaniu usługi.
  • Dodaj osoby do pokoju czatu.
  • Aby podać szczegółowe informacje o przerwie w działaniu usługi, opublikuj wiadomość w pokoju czatu.

Poniższy diagram przedstawia asynchroniczną sekwencję wiadomości między aplikacją Google Chat a pokojem czatu:

Uwierzytelnianie wymagane dla wiadomości asynchronicznych
Rysunek 3. Wiadomości asynchroniczne wymagają uwierzytelniania.

  1. Aplikacja do obsługi czatu tworzy wiadomość, wywołując interfejs Chat API za pomocą metody spaces.messages.create i umieszcza dane logowania użytkownika w żądaniu HTTP.
  2. Google Chat uwierzytelnia aplikację Google Chat za pomocą konta usługi lub danych logowania użytkownika.
  3. Google Chat renderuje wiadomość z aplikacji w określonym pokoju czatu.

Zakresy interfejsu Chat API

Skonfiguruj ekran zgody OAuth i wybierz zakresy, aby określić, jakie informacje będą widoczne dla użytkowników i weryfikatorów aplikacji, oraz zarejestrować aplikację, aby móc ją później opublikować.

Aby określić poziom dostępu przyznany aplikacji, musisz określić i zadeklarować zakresy autoryzacji. Zakres autoryzacji to ciąg identyfikatora URI OAuth 2.0 zawierający nazwę aplikacji Google Workspace, rodzaj danych, do których uzyskuje ona dostęp, oraz poziom dostępu.

Zakresy niewrażliwe

Kod zakresu Opis
https://www.googleapis.com/auth/chat.bot

Zakres chat.bot obsługuje tylko konta usługi. Korzystając z tego zakresu, nie możesz uwierzytelniać się za pomocą danych logowania użytkownika ani przekazywać dostępu w całej domenie.

Pozwala aplikacjom do obsługi czatu wyświetlać czaty i wysyłać wiadomości. Daje dostęp do wszystkich funkcji dostępnych dla aplikacji do obsługi czatu.

Zakresy wrażliwe

Kod zakresu Opis
https://www.googleapis.com/auth/chat.spaces Tworzenie rozmów i pokoi oraz wyświetlanie i edytowanie metadanych (w tym ustawień historii i ustawień dostępu) w Google Chat.
https://www.googleapis.com/auth/chat.spaces.create tworzyć nowych rozmów w Google Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Wyświetlanie czatu i pokoi w Google Chat.
https://www.googleapis.com/auth/chat.memberships Wyświetlanie, dodawanie, aktualizowanie i usuwanie uczestników rozmów w Google Chat.
https://www.googleapis.com/auth/chat.memberships.app Dodawanie siebie do rozmów w Google Chat i usuwanie się z nich.
https://www.googleapis.com/auth/chat.memberships.readonly Wyświetlanie uczestników rozmów w Google Chat.
https://www.googleapis.com/auth/chat.messages.create Tworzenie i wysyłanie wiadomości w Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions Wyświetlanie, dodawanie i usuwanie reakcji na wiadomości w Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create Dodawanie reakcji do wiadomości w Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Wyświetlanie reakcji na wiadomość w Google Chat.
https://www.googleapis.com/auth/chat.users.readstate Wyświetlanie i modyfikowanie czasu ostatniego odczytu rozmów w Google Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly Wyświetlanie czasu ostatniego odczytu rozmów w Google Chat.
https://www.googleapis.com/auth/chat.admin.spaces.readonly Wyświetlanie w Google Chat czatu i pokoi należących do domeny administratora.
https://www.googleapis.com/auth/chat.admin.memberships.readonly Wyświetlanie członków i menedżerów w rozmowach należących do domeny administratora w Google Chat.
https://www.googleapis.com/auth/chat.admin.memberships Wyświetlanie, dodawanie, aktualizowanie i usuwanie członków oraz menedżerów w rozmowach należących do domeny administratora w Google Chat.

Zakresy z ograniczeniami

Kod zakresu Opis
https://www.googleapis.com/auth/chat.delete usuwać rozmowy i pokoje oraz usuwać dostęp do powiązanych plików w Google Chat.
https://www.googleapis.com/auth/chat.import Importuj pokoje, wiadomości i subskrypcje do Google Chat. Więcej informacji znajdziesz w artykule o autoryzowaniu aplikacji Google Chat do importowania danych.
https://www.googleapis.com/auth/chat.messages Wyświetlanie, tworzenie, wysyłanie, aktualizowanie i usuwanie wiadomości oraz dodawanie, wyświetlanie i usuwanie reakcji na wiadomości.
https://www.googleapis.com/auth/chat.messages.readonly Wyświetlanie wiadomości i reakcji w Google Chat.
https://www.googleapis.com/auth/chat.admin.delete Usuwanie rozmów i pokoi należących do domeny administratora oraz odbieranie dostępu do powiązanych plików w Google Chat.

Zakresy w poprzednich tabelach wskazują ich wrażliwość, zgodnie z tymi definicjami:

Jeśli Twoja aplikacja wymaga dostępu do innych interfejsów API Google, możesz też dodać te zakresy. Więcej informacji o zakresach interfejsów API Google znajdziesz w artykule o korzystaniu z protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google.

Więcej informacji o zakresach dla interfejsów API Google Workspace znajdziesz w artykule Konfigurowanie ekranu zgody OAuth i wybieranie zakresów.

Rodzaje wymaganego uwierzytelniania

Są 2 sposoby uwierzytelniania i autoryzowania aplikacji do obsługi czatu przy użyciu interfejsu Chat API: dane logowania użytkowników i konta usługi.

Dzięki autoryzacji danych logowania użytkownika aplikacja do obsługi czatu może uzyskiwać dostęp do danych użytkownika i wykonywać działania w jego imieniu. Zakresy protokołu OAuth określają autoryzowane dane i działania.

Dzięki autoryzacji aplikacji aplikacja do obsługi czatu uzyskuje dostęp do interfejsu API jako aplikacja za pomocą danych logowania do konta usługi. Autoryzacja aplikacji zawsze używa zakresu autoryzacji chat.bot.

Wybierając typ danych logowania, które mają być używane w przypadku konkretnego żądania do interfejsu API, pamiętaj, że niektóre metody interfejsu API obsługują tylko określony typ danych logowania. Jeśli metoda interfejsu API obsługuje oba te dane, na zwracany wynik wpływa typ danych logowania użytych w wywołaniu:

  • W przypadku autoryzacji aplikacji metody zwracają tylko zasoby, do których aplikacja ma dostęp.
  • W przypadku autoryzacji użytkownika metody zwracają tylko te zasoby, do których użytkownik ma dostęp w interfejsie Google Chat.

Na przykład wywołanie metody ListSpaces z autoryzacją aplikacji zwróci listę pokoi, do których należy aplikacja. Wywołanie ListSpaces z autoryzacją użytkownika zwraca listę pokoi, do których należy ten użytkownik. W praktyce aplikacja może używać obu typów autoryzacji podczas wywoływania interfejsu Chat API w zależności od tego, jakich funkcji potrzebujesz.

Asynchroniczne wywołania interfejsu Chat API

W tabeli poniżej znajdziesz metody interfejsu Chat API i obsługiwane przez nie zakresy autoryzacji:

Metoda Uwierzytelnianie użytkowników obsługiwane Obsługiwane uwierzytelnianie aplikacji Obsługiwane zakresy autoryzacji
Pokoje  
Tworzenie pokoju W przypadku uwierzytelniania użytkowników:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Konfigurowanie pokoju W przypadku uwierzytelniania użytkowników:
  • chat.spaces.create
  • chat.spaces
Uzyskaj pokój W przypadku uwierzytelniania użytkowników:
  • chat.spaces.readonly
  • chat.spaces
Z uwierzytelnianiem aplikacji:
  • chat.bot
Wyświetlanie listy pokoi W przypadku uwierzytelniania użytkowników:
  • chat.spaces.readonly
  • chat.spaces
Z uwierzytelnianiem aplikacji:
  • chat.bot
Wyszukaj pokoje W przypadku uwierzytelniania użytkowników przy użyciu uprawnień administratora:
  • chat.admin.spaces.readonly
Aktualizowanie pokoju W przypadku uwierzytelniania użytkowników:
  • chat.spaces
  • chat.import
Usuwanie pokoju W przypadku uwierzytelniania użytkowników:
  • chat.delete
  • chat.import
W przypadku uwierzytelniania użytkowników przy użyciu uprawnień administratora:
  • chat.admin.delete
Importowanie pokoju W przypadku uwierzytelniania użytkowników:
  • chat.import
Znajdowanie czatu W przypadku uwierzytelniania użytkowników:
  • chat.spaces.readonly
  • chat.spaces
Z uwierzytelnianiem aplikacji:
  • chat.bot
Członkowie  
Tworzenie subskrypcji W przypadku uwierzytelniania użytkowników:
  • chat.memberships
  • chat.memberships.app
  • chat.import
W przypadku uwierzytelniania użytkowników przy użyciu uprawnień administratora:
  • chat.admin.memberships
Jak uzyskać subskrypcję W przypadku uwierzytelniania użytkowników:
  • chat.memberships.readonly
  • chat.memberships
Z uwierzytelnianiem aplikacji:
  • chat.bot
Członkowie grupy W przypadku uwierzytelniania użytkowników:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Z uwierzytelnianiem aplikacji:
  • chat.bot
W przypadku uwierzytelniania użytkowników przy użyciu uprawnień administratora:
  • chat.admin.memberships.readonly
Usuwanie użytkownika W przypadku uwierzytelniania użytkowników:
  • chat.memberships
  • chat.memberships.app
  • chat.import
W przypadku uwierzytelniania użytkowników przy użyciu uprawnień administratora:
  • chat.admin.memberships
Aktualizowanie członka W przypadku uwierzytelniania użytkowników:
  • chat.memberships
  • chat.import
Wiadomości  
Tworzenie wiadomości W przypadku uwierzytelniania użytkowników:
  • chat.messages.create
  • chat.messages
  • chat.import
Z uwierzytelnianiem aplikacji:
  • chat.bot
Odbieranie wiadomości W przypadku uwierzytelniania użytkowników:
  • chat.messages.readonly
  • chat.messages
Z uwierzytelnianiem aplikacji:
  • chat.bot
Wyświetlanie listy wiadomości W przypadku uwierzytelniania użytkowników:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Aktualizowanie wiadomości W przypadku uwierzytelniania użytkowników:
  • chat.messages
  • chat.import
Z uwierzytelnianiem aplikacji:
  • chat.bot
Usuwanie wiadomości W przypadku uwierzytelniania użytkowników:
  • chat.messages
  • chat.import
Z uwierzytelnianiem aplikacji:
  • chat.bot
Reakcje  
Tworzenie reakcji W przypadku uwierzytelniania użytkowników:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Reakcje na liście W przypadku uwierzytelniania użytkowników:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Usuwanie reakcji W przypadku uwierzytelniania użytkowników:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Multimedia i załączniki  
Przesyłanie multimediów jako załącznika W przypadku uwierzytelniania użytkowników:
  • chat.messages.create
  • chat.messages
  • chat.import
Pobieranie multimediów W przypadku uwierzytelniania użytkowników:
  • chat.messages.readonly
  • chat.messages
Z uwierzytelnianiem aplikacji:
  • chat.bot
Pobieranie załącznika do wiadomości Z uwierzytelnianiem aplikacji:
  • chat.bot
Stany odczytu użytkownika
Pobieranie stanu odczytu pokoju użytkownika W przypadku uwierzytelniania użytkowników:
  • chat.users.readstate
  • chat.users.readstate.readonly
Aktualizowanie stanu odczytu pokoju użytkownika W przypadku uwierzytelniania użytkowników:
  • chat.users.readstate
Pobieranie stanu przeczytania wątku użytkownika W przypadku uwierzytelniania użytkowników:
  • chat.users.readstate
  • chat.users.readstate.readonly
Wydarzenia dotyczące pokoju
Otrzymuj informacje o wydarzeniach kosmicznych W przypadku uwierzytelniania użytkowników:
  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly
Wyświetl listę zdarzeń w pokoju W przypadku uwierzytelniania użytkowników:
  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly

Zdarzenia interakcji z aplikacją Google Chat

W tabeli poniżej znajdziesz typowe sposoby interakcji użytkowników z aplikacjami Google Chat oraz informacje o tym, czy uwierzytelnianie jest wymagane czy obsługiwane:

Scenariusz Uwierzytelnianie nie jest wymagane Uwierzytelnianie użytkowników obsługiwane Obsługiwane uwierzytelnianie aplikacji
Odbieraj wiadomości od:
Zdarzenia interakcji z aplikacją Google Chat
Wywołania zwrotne Apps Script
Google Cloud Pub/Sub,
Odpowiadanie na wiadomości:
synchronicznie za pomocą zdarzenia interakcji z Google Chat,
synchronicznie z użyciem wartości zwróconej wywołania zwrotnego Apps Script;
Wysyłanie nowych wiadomości:
za pomocą przychodzących webhooków,