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

Uwierzytelnianie i autoryzacja to mechanizmy używane do weryfikacji tożsamości oraz dostępu do zasobów. Ten dokument opisuje, jak działają uwierzytelnianie i autoryzacja w przypadku żądań z aplikacji do obsługi czatu oraz żądań do interfejsu Chat API.

Omówienie procesu

Ten diagram przedstawia ogólne kroki uwierzytelniania i autoryzacji w Google Chat:

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

  1. Skonfiguruj projekt Google Cloud, włącz Chat API i aplikację Google Chat: podczas tworzenia projektu Google Cloud. W projekcie Google Cloud włączysz interfejs Chat API, skonfigurujesz aplikację do obsługi czatu i skonfigurujesz uwierzytelnianie. Więcej informacji znajdziesz w artykułach Tworzenie wersji w Google Workspace i Tworzenie aplikacji do obsługi czatu.

  2. Wywołanie interfejsu API czatu: gdy aplikacja wywołuje interfejs Chat API, wysyła dane uwierzytelniające do tego interfejsu. 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óry nie został jeszcze przyznany, pojawi się prośba o zalogowanie.

  3. Poproś o zasoby: aplikacja prosi o dostęp przy użyciu zakresów określonych podczas konfigurowania uwierzytelniania.

  4. Poproś o zgodę: jeśli aplikacja uwierzytelnia się jako użytkownik, Google wyświetla ekran zgody OAuth, aby użytkownik mógł zdecydować, czy przyznać jej dostęp do wybranych danych. Uwierzytelnianie przy użyciu 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 połączy w żądanie dane logowania i zakresy zatwierdzone przez użytkownika. Żądanie jest wysyłane do serwera autoryzacji Google, aby uzyskać token 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łączy wszystkie funkcje ograniczone przez token.

  7. Dostęp do wybranych zasobów:aplikacja używa tokena dostępu Google, by wywoływać interfejs Chat API i uzyskiwać dostęp do zasobów interfejsu Chat API.

  8. Wygeneruj token odświeżania (opcjonalnie): jeśli aplikacja musi korzystać z interfejsu Google Chat API przez cały okres istnienia jednego tokena dostępu, może go uzyskać. Więcej informacji znajdziesz w artykule Uzyskiwanie dostępu do interfejsów API Google przy użyciu protokołu OAuth 2.0.

  9. Poproś o więcej zasobów: jeśli aplikacja potrzebuje więcej dostępu, poprosi użytkownika o przyznanie nowych zakresów, co spowoduje przesłanie nowego żądania dostępu do tokena dostępu (kroki 3–6).

Kiedy aplikacje do obsługi czatu wymagają uwierzytelniania

Aplikacje do Google Chat mogą wysyłać wiadomości Google Chat synchronicznie lub synchronicznie. Mogą też wykonywać czynności takie jak tworzenie pokoju czatu w imieniu użytkownika.

Wiadomości synchroniczne nie wymagają uwierzytelniania, chyba że podczas przetwarzania odpowiedzi aplikacja do obsługi czatu wywołuje interfejs Chat API lub inny interfejs Google API.

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

Wiadomości synchroniczne nie wymagają uwierzytelniania

Wiadomości synchroniczne to odpowiedzi na zdarzenia z Google Chat. Po skonfigurowaniu i opublikowaniu aplikacji Google Chat aplikacje Google Chat mogą odbierać zdarzenia i odpowiadać na nie oraz nie wymagają uwierzytelniania ani autoryzacji.

Przykłady synchronicznych wydarzeń w Google Chat:

  • Użytkownik wysyła wiadomość w aplikacji Google Chat w Google Chat.
  • Użytkownik wspomniał o aplikacji Google Chat.
  • Użytkownik wywołuje jedno z poleceń ukośnika aplikacji Google Chat.

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

Zgoda na wyświetlanie wiadomości synchronicznych nie jest wymagana
Ilustracja 2. Wiadomości synchroniczne nie wymagają uwierzytelniania.

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

Ta sekwencja jest powtarzana w przypadku każdego zdarzenia z Google Chat.

Wiadomości asynchroniczne wymagają uwierzytelnienia

Komunikaty asynchroniczne występują, gdy aplikacja do obsługi czatu wysyła żądanie do Chat API, które wymaga uwierzytelnienia i autoryzacji.

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

  • Utwórz pokój czatu, aby przeanalizować i naprawić przerwę w działaniu usługi.
  • Dodaj osoby do pokoju czatu.
  • Opublikuj wiadomość w pokoju czatu, aby przekazać szczegółowe informacje o przerwie.

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

Uwierzytelnianie wymagane dla wiadomości asynchronicznych
Ilustracja 3. Wiadomości asynchroniczne wymagają uwierzytelnienia.

  1. Aplikacja Google Chat tworzy wiadomość, wywołując interfejs Chat API za pomocą interfejsu spaces.messages.create method i podając 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ść aplikacji w określonym pokoju czatu.

Zakresy interfejsu Chat API

Aby zdefiniować 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, rodzaje danych, do których uzyskiwany jest dostęp, oraz poziom dostępu.

Google Chat obsługuje te zakresy:

Zakres interfejsu Google Chat API Opis
https://www.googleapis.com/auth/chat.bot Zezwala aplikacjom do obsługi czatu na wyświetlanie czatów i wysyłanie wiadomości. Przyznaje dostęp do wszystkich funkcji dostępnych dla aplikacji do obsługi czatu.
https://www.googleapis.com/auth/chat.delete Usuń rozmowy i pokoje oraz dostęp do powiązanych plików w Google Chat.
Wspieranie kanału  
https://www.googleapis.com/auth/chat.memberships Wyświetlanie, dodawanie i usuwanie uczestników rozmowy w Google Chat.
https://www.googleapis.com/auth/chat.memberships.app Pozwala aplikacji Google Chat dodawać się do rozmów w Google Chat i z nich usuwać (ale nie inne aplikacje).
https://www.googleapis.com/auth/chat.memberships.readonly Uzyskiwanie szczegółowych informacji o członkostwie i wyświetlaniu listy osób w pokoju.
Wiadomości  
https://www.googleapis.com/auth/chat.messages Tworzenie, pobieranie, aktualizowanie, usuwanie i wyświetlanie wiadomości w Google Chat
https://www.googleapis.com/auth/chat.messages.create Tworzenie wiadomości i przesyłanie załączników 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 na wiadomości w Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Wyświetlanie reakcji na wiadomości w Google Chat.
https://www.googleapis.com/auth/chat.messages.readonly Wyświetlanie i wyświetlanie wiadomości w Google Chat.
Pokoje  
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 rozmów w Google Chat.
https://www.googleapis.com/auth/chat.spaces.readonly wyświetlać czat i pokoje w Google Chat,

Więcej informacji o zakresach interfejsów API Google Workspace znajdziesz w artykule Wybieranie zakresów dla aplikacji.

Listę dostępnych zakresów znajdziesz w artykule Zakresy OAuth 2.0 dla interfejsów API Google.

Rodzaje wymaganych uwierzytelniania

Aplikacje Google Chat mogą uwierzytelniać i autoryzować dane na 2 sposoby: używając danych logowania użytkownika lub kont usługi.

Dzięki autoryzacji danych logowania użytkowników Google Chat może uzyskiwać dostęp do danych użytkownika i wykonywać działania w jego imieniu. Zakresy OAuth określają autoryzowane dane i działania. Tych aplikacji Google Chat nie można jednak udostępniać publicznie. Więcej informacji znajdziesz w artykule Publikowanie aplikacji Google Chat.

Dzięki autoryzacji aplikacji Google Chat uzyskuje dostęp do interfejsu API jako aplikacji przy użyciu danych logowania konta usługi. Autoryzacja aplikacji zawsze używa zakresu autoryzacji chat.bot.

Jeśli jesteś administratorem domeny, możesz przyznać upoważnienie w całej domenie do autoryzowania konta usługi aplikacji, aby umożliwić dostęp do danych użytkowników bez potrzeby uzyskiwania zgody każdego użytkownika. Po skonfigurowaniu przekazywania dostępu w całej domenie możesz wykonywać wywołania interfejsu API przy użyciu konta usługi, by podszywać się pod konta użytkowników. Chociaż konto usługi jest używane do uwierzytelniania, przekazywanie dostępu w całej domenie może podszywać się pod użytkowników, dlatego jest uznawane za uwierzytelnianie użytkownika. Wszystkie funkcje, które wymagają uwierzytelniania użytkowników, mogą korzystać z przekazywania dostępu w całej domenie.

Podczas wybierania typu danych logowania, których chcesz użyć w przypadku konkretnego żądania do interfejsu API, pamiętaj, że niektóre metody API obsługują tylko określony typ danych logowania. Jeśli metoda API obsługuje oba rodzaje danych logowania, typ zwracanych w nich danych uwierzytelniających wpływa na zwracany wynik:

  • Gdy autoryzuje aplikację, metody zwracają tylko zasoby, do których aplikacja ma dostęp.
  • Przy użyciu autoryzacji użytkownika metody zwracają tylko zasoby, do których użytkownik ma dostęp w interfejsie Google Chat.

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

Do asynchronicznych wywołań interfejsu Chat API

W tabeli poniżej znajdziesz listę metod interfejsu API Chat oraz ich obsługiwane zakresy:

Metoda Obsługiwane jest uwierzytelnianie użytkowników. Obsługiwane uwierzytelnianie aplikacji Obsługiwane zakresy autoryzacji
Pokoje  
Tworzenie pokoju
  • chat.spaces.create
  • chat.spaces
Tworzenie pokoju
  • chat.spaces.create
  • chat.spaces
Tworzenie pokoju W przypadku uwierzytelniania użytkownika:
  • chat.spaces.readonly
  • chat.spaces
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Wyświetlanie listy pokoi W przypadku uwierzytelniania użytkownika:
  • chat.spaces.readonly
  • chat.spaces
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Aktualizowanie pokoju
  • chat.spaces
Usuwanie pokoju
  • chat.delete
Znajdowanie czatu W przypadku uwierzytelniania użytkownika:
  • chat.spaces.readonly
  • chat.spaces
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Członkowie  
Tworzenie subskrypcji
  • chat.memberships
  • chat.memberships.app
Pozyskiwanie wspierających W przypadku uwierzytelniania użytkownika:
  • chat.memberships.readonly
  • chat.memberships
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Członkowie grupy W przypadku uwierzytelniania użytkownika:
  • chat.memberships.readonly
  • chat.memberships
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Usuwanie użytkownika
  • chat.memberships
  • chat.memberships.app
Wiadomości  
Tworzenie wiadomości W przypadku uwierzytelniania użytkownika:
  • chat.messages.create
  • chat.messages
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Odbierz wiadomość W przypadku uwierzytelniania użytkownika:
  • chat.messages.readonly
  • chat.messages
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Wyświetlanie wiadomości
  • chat.messages.readonly
  • chat.messages
Aktualizowanie wiadomości W przypadku uwierzytelniania użytkownika:
  • chat.messages
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Usuwanie wiadomości W przypadku uwierzytelniania użytkownika:
  • chat.messages
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Reakcje  
Tworzenie reakcji
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
Wyświetlanie listy reakcji
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Usuwanie reakcji
  • chat.messages.reactions
  • chat.messages
Multimedia i załączniki  
Przesyłanie multimediów jako załącznika
  • chat.messages.create
  • chat.messages
Pobieranie multimediów W przypadku uwierzytelniania użytkownika:
  • chat.messages.readonly
  • chat.messages
Za pomocą uwierzytelniania aplikacji:
  • chat.bot
Pobieranie załącznika do wiadomości
  • chat.bot

Synchroniczne odbieranie interakcji użytkowników i reagowanie na nie

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 jest uwierzytelnianie użytkowników. Obsługiwane uwierzytelnianie aplikacji
Odbieraj wiadomości od:
Wydarzenia na czacie
Wywołania zwrotne Apps Script
Google Cloud Pub/Sub
Odpowiadanie na wiadomości:
Synchronicznie dzięki zdarzeniu Google Chat
Synchronicznie przez wartość wywołania zwrotnego Apps Script
Wysyłaj nowe wiadomości:
Przychodzące webhooki