Łączenie aplikacji Google Chat z innymi usługami i narzędziami

Na tej stronie dowiesz się, jak połączyć aplikację Google Chat z usługą lub narzędziem spoza Google Chat. Aplikacje do Google Chat są same w sobie bardzo przydatne, ale często współpracują z innymi systemami i wymagają aplikacji towarzyszących do łączenia kont, autoryzowania dostępu do danych, wyświetlania dodatkowych danych lub konfigurowania preferencji użytkownika.

Aby uwierzytelnić użytkowników za pomocą usługi innej firmy lub procesu OAuth, aplikacja do obsługi czatu wykonuje te czynności:

  1. Wykrywanie, kiedy wymagana jest autoryzacja lub konfiguracja
  2. Zwróć podstawową kartę autoryzacji, która wyświetla użytkownikowi prośbę o zalogowanie się lub skonfigurowanie usługi.
  3. Przekieruj do adresu URI zakończenia, aby Google Chat automatycznie ponowił pierwotną interakcję po zakończeniu autoryzacji przez użytkownika.

Architektura uwierzytelniania aplikacji Google Chat w usłudze innej firmy.

Wymagania wstępne

HTTP

Aplikacja Google Chat, która odbiera i odpowiada na interakcje użytkowników. Aby go utworzyć, wykonaj czynności opisane w krótkim wprowadzeniu do HTTP.

Google Apps Script

Aplikacja Google Chat, która odbiera i odpowiada na interakcje użytkowników. Aby utworzyć taki skrypt, wykonaj czynności opisane w krótkim wprowadzeniu do Apps Script.

wykrywać, że wymagana jest autoryzacja;

Podczas interakcji z aplikacją w Google Chat użytkownicy mogą nie mieć uprawnień dostępu do chronionego zasobu z różnych powodów, np.:

  • Token dostępu do połączenia z usługą innej firmy nie został jeszcze wygenerowany lub wygasł.
  • Token dostępu nie obejmuje żądanego zasobu.
  • Token dostępu nie obejmuje zakresów wymaganych przez żądanie.

Aplikacja w Google Chat powinna wykrywać takie przypadki, aby użytkownicy mogli się zalogować i autoryzować dostęp do Twojej usługi.

Jeśli tworzysz skrypt w Apps Script, możesz użyć biblioteki OAuth2 for Google Apps Script (lub wersji OAuth1), w której funkcja hasAccess sprawdza, czy użytkownik autoryzował dostęp do usługi. Jeśli używasz żądań UrlFetchApp.fetch, możesz ustawić parametr muteHttpExceptions na true, aby sprawdzić kod odpowiedzi i treść w zwróconym obiekcie HttpResponse.

Wyświetlanie użytkownikom podstawowej karty autoryzacji

Gdy aplikacja do obsługi czatu wykryje, że wymagana jest autoryzacja lub konfiguracja, zwróć odpowiedź AuthorizationError, aby wyświetlić użytkownikowi prywatną podstawową kartę autoryzacji.

Na ilustracji poniżej widać przykład podstawowej karty autoryzacji Google:

Podstawowy monit o autoryzację konta przykładowego.
Ilustracja 1. Podstawowy monit o autoryzację w przypadku konta przykładowego. W prompcie jest napisane, że aplikacja Google Chat chce wyświetlać dodatkowe informacje, ale w tym celu potrzebuje zgody użytkownika na dostęp do konta.

Aby wyświetlić użytkownikom podstawową kartę autoryzacji, zwróć obiekt AuthorizationError:

HTTP

Zwróć tę odpowiedź JSON:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Google Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Zastąp te elementy:

  • AUTHORIZATION_URL: adres URL HTTPS aplikacji internetowej, która obsługuje uwierzytelnianie, autoryzację lub konfigurację.
  • RESOURCE_DISPLAY_NAME: wyświetlana nazwa chronionego zasobu lub usługi. Ta nazwa jest wyświetlana użytkownikowi w prompcie autoryzacji. Jeśli na przykład Twoje RESOURCE_DISPLAY_NAME to Example Account, w prośbie pojawi się informacja, że aplikacja potrzebuje zgody na dostęp do Example Account.

Dokończ przesyłanie prośby o konfigurację

W Google Chat użytkownik może dokończyć proces autoryzacji, a Google Chat automatycznie ponowi pierwotną interakcję bez ręcznego odświeżania. Chat obsługuje automatyczne ponawianie, jeśli wyzwalaczem jest Wiadomość, Dodano do pokoju lub Polecenie aplikacji.

W przypadku tych wyzwalaczy aplikacja do obsługi czatu otrzymuje identyfikator URI przekierowania po zakończeniu (configCompleteRedirectUri / completeRedirectUri) w ładunku zdarzenia:

  • Wiadomość: chat.messagePayload.configCompleteRedirectUri
  • Dodano do pokoju: chat.addedToSpacePayload.configCompleteRedirectUri
  • Polecenie aplikacji: chat.appCommandPayload.configCompleteRedirectUri

Musisz zakodować ten identyfikator URI przekierowania w parametrze <var>AUTHORIZATION_URL</var> i po zakończeniu procesu autoryzacji przekierować do niego przeglądarkę użytkownika. Przekierowanie na ten adres URL sygnalizuje Google Chat, że prośba o autoryzację lub konfigurację została zrealizowana.

Gdy użytkownik zostanie przekierowany na identyfikator URI przekierowania po zakończeniu podany w pierwotnym ładunku zdarzenia, Google Chat wykona te czynności:

  1. Usuwa prompt autoryzacji prywatnej wyświetlany użytkownikowi, który zainicjował działanie.
  2. przekształca pierwotną wiadomość w publiczną, dzięki czemu jest ona widoczna dla innych członków pokoju;
  3. Ponownie wysyła oryginalny obiekt zdarzenia do aplikacji Google Chat.

Jeśli nie przekierujesz użytkownika do identyfikatora URI przekierowania po zakończeniu, będzie on nadal mógł dokończyć proces autoryzacji, ale Google Chat nie ponowi automatycznie poprzedniego wykonania i użytkownik będzie musiał ręcznie ponownie wywołać aplikację w Google Chat.

Odwiedzenie adresu URI przekierowania po zakończeniu wpływa tylko na jedną interakcję użytkownika. Jeśli użytkownik wysłał do aplikacji do obsługi czatu kilka wiadomości i otrzymał kilka promptów, ukończenie procesu uwierzytelniania i konfiguracji tylko w przypadku jednego promptu spowoduje ponowienie próby tylko w przypadku tej konkretnej interakcji.

Uwierzytelnianie użytkownika Google Chat poza Google Chat

Podczas łączenia z adresem URL poza Chatem (np. z wywołaniem zwrotnym OAuth) często musisz powiązać zewnętrzną sesję internetową z tożsamością użytkownika w Chat. Zalecamy zabezpieczenie docelowej aplikacji internetowej za pomocą logowania przez Google.

Użyj tokena tożsamości wydanego podczas logowania, aby uzyskać identyfikator użytkownika. Roszczenie sub zawiera unikalny identyfikator Google użytkownika i może być powiązane z nazwą zasobu użytkownika (chat.user.name) z Google Chat.

Aby powiązać roszczenie sub z nazwą zasobu users/{user} w Google Chat, dodaj przed wartością roszczenia sub znak users/. Na przykład wartość deklaracji sub równa 123 odpowiada wartości users/123 w obiektach zdarzeń wysyłanych do aplikacji do Google Chat.

Przykładowe fragmenty kodu

Poniższe przykłady kodu pokazują, jak aplikacja Google Chat może zażądać danych logowania OAuth2 offline za pomocą podstawowej karty autoryzacji, zapisać je w bazie danych, przekierować do identyfikatora URI zakończenia i wykonywać wywołania interfejsu API z uwierzytelnianiem użytkownika:

Aplikacje do obsługi czatu, które nie są dodatkami: łączenie aplikacji do obsługi czatu z innymi usługami i narzędziami

Jeśli utrzymujesz aplikację Google Chat, która nie jest dodatkiem do Google Workspace, aplikacja Google Chat wysyła żądania konfiguracji za pomocą elementu actionResponse typu REQUEST_CONFIG i odczytuje configCompleteRedirectUrl z obiektu najwyższego poziomu Event.

Aby przekształcić aplikację do czatu, która nie jest dodatkiem, w dodatek do Google Workspace, zapoznaj się z artykułem Przekształcanie aplikacji do Google Chat w dodatek do Google Workspace.

Prośba o konfigurację od użytkownika w aplikacji Google Chat, która nie jest dodatkiem

W aplikacji w Google Chat, która nie jest dodatkiem, zwróć użytkownikowi adres URL konfiguracji w następującej formie:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

To polecenie informuje Google Chat, że użytkownikowi należy wyświetlić prywatny prompt, w którym CONFIGURATION_URL to link, który użytkownik może otworzyć, aby uzyskać dodatkowe informacje o uwierzytelnianiu, autoryzacji lub konfiguracji. Odpowiedź REQUEST_CONFIG wyklucza się z zwykłą wiadomością z odpowiedzią. Wszelkie teksty, karty i inne atrybuty są ignorowane.

Dokończ prośbę o konfigurację w aplikacji Google Chat, która nie jest dodatkiem.

Każda interakcja MESSAGE, ADDED_TO_SPACE i APP_COMMANDEvent, którą otrzymuje aplikacja do obsługi czatu, która nie jest dodatkiem, zawiera pole najwyższego poziomu configCompleteRedirectUrl. Zakoduj ten adres URL w adresie URL konfiguracji i przekieruj do niego użytkownika po zakończeniu, aby Google Chat usunął prompt, przekształcił oryginalną wiadomość w publiczną i ponownie wysłał oryginalne zdarzenie interakcji do aplikacji Google Chat.

Przykładowe implementacje znajdziesz w przykładowej aplikacji do łączności w Node.js i przykładowej aplikacji do autoryzacji MyProfile w Pythonie w GitHubie.