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. Z tego dokumentu dowiesz się, jak działa uwierzytelnianie i autoryzacja 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 włączasz interfejs Chat API, konfigurujesz aplikację Google Chat i konfigurujesz uwierzytelnianie. Więcej informacji znajdziesz w artykułach na temat programowania w Google Workspace i tworzenia aplikacji Google Chat.

  2. Wywołanie interfejsu Chat API: gdy aplikacja wywołuje interfejs Chat API, wysyła do niego dane uwierzytelniające. Jeśli aplikacja uwierzytelnia się na koncie usługi, dane uwierzytelniające 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 przyznane, prosi użytkownika o zalogowanie się.

  3. Żądanie zasobów: aplikacja prosi o dostęp z zakresami podanymi przez Ciebie podczas konfigurowania uwierzytelniania.

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

  5. Wyślij zatwierdzoną prośbę o zasoby: jeśli użytkownik wyrazi zgodę na zakresy autoryzacji, aplikacja połączy dane logowania i zatwierdzone przez użytkownika zakresy w jedno żądanie. Żą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ę przyznanych zakresów. Jeśli zwrócona lista zakresów jest bardziej restrykcyjna niż żądane zakresy, aplikacja wyłącza wszystkie funkcje ograniczone przez token.

  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. Pobierz token odświeżania (opcjonalnie): jeśli Twoja aplikacja musi uzyskać dostęp do interfejsu Google Chat API po wygaśnięciu pojedynczego tokena dostępu, może otrzymać token odświeżania. Więcej informacji znajdziesz w artykule o korzystaniu z protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google.

  9. Poproś 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, aby odpowiedzieć na interakcję użytkownika, chyba że podczas przetwarzania odpowiedzi wywołają one interfejs Chat API lub inny interfejs Google API.

Aby wysyłać asynchroniczne wiadomości lub wykonywać zadania w imieniu użytkownika, aplikacje Google Chat wysyłają do interfejsu Chat API żądania REST, 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 użytkownik Google Chat, aby odbierać zdarzenia interakcji i reagować na nie synchronicznie.

Aplikacje Google Chat otrzymują zdarzenia interakcji za każdym razem, gdy użytkownik wchodzi w interakcję lub wywołuje aplikację Google Chat, w tym:

  • 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 do obsługi czatu.

Ten diagram przedstawia sekwencję żądań i odpowiedzi między użytkownikiem Google Chat a aplikacją Google Chat:

Autoryzacja zdarzeń interakcji z aplikacją Google Chat nie jest wymagana
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ź użytkownikowi lub w pokoju.

Ta sekwencja jest powtarzana przy każdym zdarzeniu interakcji z aplikacją do obsługi czatu.

Wiadomości asynchroniczne wymagają uwierzytelniania

Wiadomości asynchroniczne mają miejsce, gdy aplikacja do obsługi czatu wysyła żądanie do interfejsu Chat API, co wymaga uwierzytelnienia 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 analizowania i rozwiązywania problemów związanych z przerwami w działaniu usługi.
  • Dodaj osoby do pokoju czatu.
  • Jeśli chcesz przekazać szczegółowe informacje o przerwie w działaniu usługi, opublikuj wiadomość w pokoju czatu.

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

Wiadomości asynchroniczne wymagają uwierzytelniania
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 w żądaniu HTTP dane logowania użytkownika.
  2. Google Chat uwierzytelnia aplikację Google Chat za pomocą konta usługi lub danych logowania użytkownika.
  3. Google Chat renderuje wiadomość z aplikacji we wskazanym pokoju.

Zakresy interfejsu Chat API

Skonfiguruj ekran zgody OAuth i wybierz zakresy, aby określić, jakie informacje mają być 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 wskazać 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 ma 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. Za pomocą tego zakresu nie możesz uwierzytelniać za pomocą danych logowania użytkownika ani z przekazywaniem dostępu w całej domenie.

Umożliwia aplikacjom do obsługi czatu wyświetlanie czatów i wysyłanie wiadomości. Przyznaje 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 aktualizowanie metadanych (w tym ustawień historii) w Google Chat.
https://www.googleapis.com/auth/chat.spaces.create Tworzenie 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świetlaj, dodawaj i usuwaj 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świetl 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świetlaj, dodawaj i usuwaj reakcje 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.

Zakresy z ograniczeniami

Kod zakresu Opis
https://www.googleapis.com/auth/chat.delete usuwać rozmowy i pokoje oraz odbierać 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.

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 o konfigurowaniu ekranu zgody OAuth i wyborze zakresów.

Typy wymaganych uwierzytelniania

Są 2 sposoby uwierzytelniania i autoryzowania aplikacji do obsługi czatu przy użyciu interfejsu Chat API: dane logowania użytkownika lub 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ć w jego imieniu działania. Zakresy protokołu OAuth określają autoryzowane dane i działania. Takich aplikacji nie można jednak publikować publicznie. Więcej informacji znajdziesz w artykule Publikowanie aplikacji w Google Chat.

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

Jeśli jesteś administratorem domeny, możesz przyznać przekazywanie uprawnień w całej domenie w celu autoryzacji konta usługi aplikacji na dostęp do danych użytkowników bez konieczności udzielania zgody przez każdego z nich. Po skonfigurowaniu przekazywania dostępu w całej domenie możesz wywoływać wywołania interfejsu API przy użyciu konta usługi, aby podszywać się pod konto użytkownika. Mimo że konto usługi służy do uwierzytelniania, przekazywanie dostępu w całej domenie podszywa się pod użytkownika i dlatego jest uważane za uwierzytelnianie użytkownika. Wszystkie funkcje, które wymagają uwierzytelniania użytkowników, mogą korzystać z przekazywania w całej domenie.

Wybierając typ danych logowania, które mają być użyte w przypadku danego żą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 dane logowania, typ danych logowania użytych w wywołaniu wpływa na zwracany wynik:

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

Na przykład wywołanie metody ListSpaces z autoryzacją aplikacji zwróci listę pokoi, do których należy aplikacja. Wywołanie metody ListSpaces z autoryzacją użytkownika zwraca listę pokoi, do których użytkownik należy. 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 Obsługiwane uwierzytelnianie użytkowników Obsługiwane jest uwierzytelnianie aplikacji. Obsługiwane zakresy autoryzacji
Pokoje  
Tworzenie pokoju Przy użyciu uwierzytelniania użytkownika:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Konfigurowanie pokoju Przy użyciu uwierzytelniania użytkownika:
  • chat.spaces.create
  • chat.spaces
Rezerwowanie pokoju Przy użyciu uwierzytelniania użytkownika:
  • chat.spaces.readonly
  • chat.spaces
Z uwierzytelnianiem aplikacji:
  • chat.bot
Wyświetlanie listy pokoi Przy użyciu uwierzytelniania użytkownika:
  • chat.spaces.readonly
  • chat.spaces
Z uwierzytelnianiem aplikacji:
  • chat.bot
Aktualizowanie pokoju Przy użyciu uwierzytelniania użytkownika:
  • chat.spaces
  • chat.import
Usuwanie pokoju Przy użyciu uwierzytelniania użytkownika:
  • chat.delete
  • chat.import
Importowanie pokoju Przy użyciu uwierzytelniania użytkownika:
  • chat.import
Znajdowanie czatu Przy użyciu uwierzytelniania użytkownika:
  • chat.spaces.readonly
  • chat.spaces
Z uwierzytelnianiem aplikacji:
  • chat.bot
Członkowie  
Tworzenie subskrypcji Przy użyciu uwierzytelniania użytkownika:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Kup subskrypcję Przy użyciu uwierzytelniania użytkownika:
  • chat.memberships.readonly
  • chat.memberships
Z uwierzytelnianiem aplikacji:
  • chat.bot
Członkowie listy Przy użyciu uwierzytelniania użytkownika:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Z uwierzytelnianiem aplikacji:
  • chat.bot
Usuwanie użytkownika Przy użyciu uwierzytelniania użytkownika:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Wiadomości  
Tworzenie wiadomości Przy użyciu uwierzytelniania użytkownika:
  • chat.messages.create
  • chat.messages
  • chat.import
Z uwierzytelnianiem aplikacji:
  • chat.bot
Otrzymywanie wiadomości Przy użyciu uwierzytelniania użytkownika:
  • chat.messages.readonly
  • chat.messages
Z uwierzytelnianiem aplikacji:
  • chat.bot
Wyświetl listę wiadomości Przy użyciu uwierzytelniania użytkownika:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Aktualizowanie wiadomości Przy użyciu uwierzytelniania użytkownika:
  • chat.messages
  • chat.import
Z uwierzytelnianiem aplikacji:
  • chat.bot
Usuwanie wiadomości Przy użyciu uwierzytelniania użytkownika:
  • chat.messages
  • chat.import
Z uwierzytelnianiem aplikacji:
  • chat.bot
Reakcje  
Tworzenie reakcji Przy użyciu uwierzytelniania użytkownika:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Reakcje na liście Przy użyciu uwierzytelniania użytkownika:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Usuwanie reakcji Przy użyciu uwierzytelniania użytkownika:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Multimedia i załączniki  
Przesyłanie multimediów jako załącznika Przy użyciu uwierzytelniania użytkownika:
  • chat.messages.create
  • chat.messages
  • chat.import
Pobieranie multimediów Przy użyciu uwierzytelniania użytkownika:
  • chat.messages.readonly
  • chat.messages
Z uwierzytelnianiem aplikacji:
  • chat.bot
Pobieranie załącznika do wiadomości Z użyciem uwierzytelniania aplikacji:
  • chat.bot

W przypadku zdarzeń 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 Obsługiwane uwierzytelnianie użytkowników Obsługiwane jest 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 aplikacją Google Chat,
synchronicznie, przy użyciu wartości wywołania zwrotnego Apps Script;
Wysyłaj nowe wiadomości:
za pomocą przychodzących webhooków,