Tworzenie aplikacji HTTP Google Chat

Na tej stronie dowiesz się, jak utworzyć dodatek do Google Workspace, który działa w Google Chat, przy użyciu usługi HTTP.

Z tego krótkiego wprowadzenia dowiesz się, jak utworzyć usługę HTTP za pomocą usług Google Cloud. Aby utworzyć aplikację Google Chat, napisz i wdrożysz funkcję Cloud Run, której aplikacja Google Chat używa do odpowiadania na wiadomości użytkownika.

W architekturze HTTP konfigurujesz Chat tak, aby integrować się z Google Cloud lub serwerem lokalnym za pomocą protokołu HTTP, jak pokazano na tym diagramie:

Architektura aplikacji Google Chat korzystającej z usługi internetowej na serwerze lokalnym.

Na powyższym diagramie użytkownik wchodzący w interakcję z aplikacją HTTP Chat ma następujący przepływ informacji:

  1. Użytkownik wysyła wiadomość w Google Chat do aplikacji w Google Chat – w wiadomości bezpośredniej lub w pokoju w Google Chat.
  2. Żądanie HTTP jest wysyłane do serwera WWW, który jest systemem w chmurze lub systemem lokalnym zawierającym logikę aplikacji Google Chat.
  3. Opcjonalnie logika aplikacji Chat może być zintegrowana z usługami Google Workspace (takimi jak Kalendarz i Arkusze), innymi usługami Google (takimi jak Mapy, YouTube i Vertex AI) lub innymi usługami internetowymi (takimi jak system zarządzania projektami czy narzędzie do obsługi zgłoszeń).
  4. Serwer WWW wysyła odpowiedź HTTP z powrotem do usługi aplikacji Chat w Google Chat.
  5. Odpowiedź jest dostarczana do użytkownika.
  6. Opcjonalnie aplikacja Chat może wywoływać interfejs Chat API, aby asynchronicznie publikować wiadomości lub wykonywać inne operacje.

Ta architektura zapewnia elastyczność w zakresie korzystania z istniejących bibliotek i komponentów, które są już dostępne w systemie, ponieważ aplikacje do czatu można projektować w różnych językach programowania.

Cele

  • skonfigurować środowisko,
  • Utwórz i wdróż funkcję Cloud Run.
  • Skonfiguruj dodatek do Google Workspace dla aplikacji do czatu.
  • Przetestuj aplikację.

Wymagania wstępne

Konfigurowanie środowiska

Zanim zaczniesz korzystać z interfejsów Google API, musisz je włączyć w projekcie Google Cloud. W jednym projekcie Google Cloud możesz włączyć co najmniej 1 interfejs API.
  • W konsoli Google Cloud włącz interfejsy Cloud Build API, Cloud Functions API, Cloud Pub/Sub API, Cloud Logging API, Artifact Registry API i Cloud Run API.

    Włączanie interfejsów API

Tworzenie i wdrażanie funkcji Cloud Run

Utwórz i wdróż funkcję Cloud Run, która generuje kartę Google Chat z wyświetlaną nazwą nadawcy i obrazem awatara. Gdy aplikacja Chat otrzyma wiadomość, uruchomi funkcję i odpowie kartą.

Aby utworzyć i wdrożyć funkcję aplikacji Chat, wykonaj te czynności:

Node.js

  1. W konsoli Google Cloud otwórz stronę Cloud Run:

    Otwórz Cloud Run

    Sprawdź, czy wybrany jest projekt aplikacji do obsługi czatu.

  2. Kliknij Napisz funkcję.

  3. Na stronie Utwórz usługę skonfiguruj funkcję:

    1. W polu Nazwa usługi wpisz addonchatapp.
    2. Na liście Region wybierz region.
    3. Na liście Środowisko wykonawcze wybierz najnowszą wersję Node.js.
    4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
    5. Kliknij Utwórz i poczekaj, aż Cloud Run utworzy usługę. Konsola przekieruje Cię na kartę Źródło.
  4. Na karcie Źródło:

    1. W polu Punkt wejścia usuń tekst domyślny i wpisz avatarApp.
    2. Zastąp zawartość pliku index.js tym kodem:
    node/chat/avatar-app/index.js
    import { http } from '@google-cloud/functions-framework';
    
    // The ID of the slash command "/about".
    // You must use the same ID in the Google Chat API configuration.
    const ABOUT_COMMAND_ID = 1;
    
    /**
     * Handle requests from Google Workspace add on
     *
     * @param {Object} req Request sent by Google Chat
     * @param {Object} res Response to be sent back to Google Chat
     */
    http('avatarApp', (req, res) => {
      const chatEvent = req.body.chat;
      let message;
      if (chatEvent.appCommandPayload) {
        message = handleAppCommand(chatEvent);
      } else {
        message = handleMessage(chatEvent);
      }
      res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
        message: message
      }}}});
    });
    
    /**
     * Responds to an APP_COMMAND event in Google Chat.
     *
     * @param {Object} event the event object from Google Chat
     * @return the response message object.
     */
    function handleAppCommand(event) {
      switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
        case ABOUT_COMMAND_ID:
          return {
            text: 'The Avatar app replies to Google Chat messages.'
          };
      }
    }
    
    /**
     * Responds to a MESSAGE event in Google Chat.
     *
     * @param {Object} event the event object from Google Chat
     * @return the response message object.
     */
    function handleMessage(event) {
      // Stores the Google Chat user as a variable.
      const chatUser = event.messagePayload.message.sender;
      const displayName = chatUser.displayName;
      const avatarUrl = chatUser.avatarUrl;
      return {
        text: 'Here\'s your avatar',
        cardsV2: [{
          cardId: 'avatarCard',
          card: {
            name: 'Avatar Card',
            header: {
              title: `Hello ${displayName}!`,
            },
            sections: [{ widgets: [{
              textParagraph: { text: 'Your avatar picture: ' }
            }, {
              image: { imageUrl: avatarUrl }
            }]}]
          }
        }]
      };
    }
    1. Kliknij Zapisz i wdroż ponownie.

Python

  1. W konsoli Google Cloud otwórz stronę Cloud Run:

    Otwórz Cloud Run

    Sprawdź, czy wybrany jest projekt aplikacji do obsługi czatu.

  2. Kliknij Napisz funkcję.

  3. Na stronie Utwórz usługę skonfiguruj funkcję:

    1. W polu Nazwa usługi wpisz addonchatapp.
    2. Na liście Region wybierz region.
    3. Na liście Środowisko wykonawcze wybierz najnowszą wersję Pythona.
    4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
    5. Kliknij Utwórz i poczekaj, aż Cloud Run utworzy usługę. Konsola przekieruje Cię na kartę Źródło.
  4. Na karcie Źródło:

    1. W polu Punkt wejścia usuń tekst domyślny i wpisz avatar_app.
    2. Zastąp zawartość pliku main.py tym kodem:
    python/chat/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # The ID of the slash command "/about".
    # You must use the same ID in the Google Chat API configuration.
    ABOUT_COMMAND_ID = 1
    
    @functions_framework.http
    def avatar_app(req: flask.Request) -> Mapping[str, Any]:
      """Handle requests from Google Workspace add on
    
      Args:
        flask.Request req: the request sent by Google Chat
    
      Returns:
        Mapping[str, Any]: the response to be sent back to Google Chat
      """
      chat_event = req.get_json(silent=True)["chat"]
      if chat_event and "appCommandPayload" in chat_event:
        message = handle_app_command(chat_event)
      else:
        message = handle_message(chat_event)
      return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
          "message": message
      }}}}
    
    def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
      """Responds to an APP_COMMAND event in Google Chat.
    
      Args:
        Mapping[str, Any] event: the event object from Google Chat
    
      Returns:
        Mapping[str, Any]: the response message object.
      """
      if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
        return {
          "text": "The Avatar app replies to Google Chat messages.",
        }
      return {}
    
    def handle_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
      """Responds to a MESSAGE event in Google Chat.
    
      Args:
        Mapping[str, Any] event: the event object from Google Chat
    
      Returns:
        Mapping[str, Any]: the response message object.
      """
      # Stores the Google Chat user as a variable.
      chat_user = event["messagePayload"]["message"]["sender"]
      display_name = chat_user.get("displayName", "")
      avatar_url = chat_user.get("avatarUrl", "")
      return {
        "text": "Here's your avatar",
        "cardsV2": [{
          "cardId": "avatarCard",
          "card": {
            "name": "Avatar Card",
            "header": {
              "title": f"Hello {display_name}!"
            },
            "sections": [{ "widgets": [
              { "textParagraph": { "text": "Your avatar picture:" }},
              { "image": { "imageUrl": avatar_url }},
            ]}]
          }
        }]
      }
    1. Kliknij Zapisz i wdroż ponownie.

Java

  1. W konsoli Google Cloud otwórz stronę Cloud Run:

    Otwórz Cloud Run

    Sprawdź, czy wybrany jest projekt aplikacji do obsługi czatu.

  2. Kliknij Napisz funkcję.

  3. Na stronie Utwórz usługę skonfiguruj funkcję:

    1. W polu Nazwa usługi wpisz addonchatapp.
    2. Na liście Region wybierz region.
    3. Na liście Środowisko wykonawcze wybierz najnowszą wersję Javy.
    4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
    5. Kliknij Utwórz i poczekaj, aż Cloud Run utworzy usługę. Konsola przekieruje Cię na kartę Źródło.
  4. Na karcie Źródło:

    1. W polu Punkt wejścia usuń tekst domyślny i wpisz App.
    2. Zmień nazwę domyślnego pliku Java na src/main/java/com/google/chat/avatar/App.java.
    3. Zastąp zawartość pliku App.java tym kodem:
    java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java
    package com.google.chat.avatar;
    
    import com.google.api.services.chat.v1.model.CardWithId;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1Card;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1Image;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1Section;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget;
    import com.google.api.services.chat.v1.model.Message;
    import com.google.cloud.functions.HttpFunction;
    import com.google.cloud.functions.HttpRequest;
    import com.google.cloud.functions.HttpResponse;
    import com.google.gson.Gson;
    import com.google.gson.JsonObject;
    import java.util.List;
    
    public class App implements HttpFunction {
      // The ID of the slash command "/about".
      // You must use the same ID in the Google Chat API configuration.
      private static final int ABOUT_COMMAND_ID = 1;
    
      private static final Gson gson = new Gson();
    
      /**
       * Handle requests from Google Workspace add on
       * 
       * @param request the request sent by Google Chat
       * @param response the response to be sent back to Google Chat
       */
      @Override
      public void service(HttpRequest request, HttpResponse response) throws Exception {
        JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
        JsonObject chatEvent = event.getAsJsonObject("chat");
        Message message;
        if (chatEvent.has("appCommandPayload")) {
          message = handleAppCommand(chatEvent);
        } else {
          message = handleMessage(chatEvent);
        }
        JsonObject createMessageAction = new JsonObject();
        createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
        JsonObject chatDataAction = new JsonObject();
        chatDataAction.add("createMessageAction", createMessageAction);
        JsonObject hostAppDataAction = new JsonObject();
        hostAppDataAction.add("chatDataAction", chatDataAction);
        JsonObject dataActions = new JsonObject();
        dataActions.add("hostAppDataAction", hostAppDataAction);
        response.getWriter().write(gson.toJson(dataActions));
      }
    
      /**
       * Handles an APP_COMMAND event in Google Chat.
       *
       * @param event the event object from Google Chat
       * @return the response message object.
       */
      private Message handleAppCommand(JsonObject event) throws Exception {
        switch (event.getAsJsonObject("appCommandPayload")
          .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
          case ABOUT_COMMAND_ID:
            return new Message()
              .setText("The Avatar app replies to Google Chat messages.");
          default:
            return null;
        }
      }
    
      /**
       * Handles a MESSAGE event in Google Chat.
       *
       * @param event the event object from Google Chat
       * @return the response message object.
       */
      private Message handleMessage(JsonObject event) throws Exception {
        // Stores the Google Chat user as a variable.
        JsonObject chatUser = event.getAsJsonObject("messagePayload").getAsJsonObject("message").getAsJsonObject("sender");
        String displayName = chatUser.has("displayName") ? chatUser.get("displayName").getAsString() : "";
        String avatarUrl = chatUser.has("avatarUrl") ? chatUser.get("avatarUrl").getAsString() : "";
        return new Message()
          .setText("Here's your avatar")
          .setCardsV2(List.of(new CardWithId()
            .setCardId("avatarCard")
            .setCard(new GoogleAppsCardV1Card()
              .setName("Avatar Card")
              .setHeader(new GoogleAppsCardV1CardHeader()
                .setTitle(String.format("Hello %s!", displayName)))
              .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
                new GoogleAppsCardV1Widget().setTextParagraph(new GoogleAppsCardV1TextParagraph()
                  .setText("Your avatar picture:")),
                new GoogleAppsCardV1Widget()
                  .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
      }
    }
  5. Zastąp zawartość pliku pom.xml tym kodem:

    java/chat/avatar-app/pom.xml
    <project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
    
      <groupId>com.google.chat</groupId>
      <artifactId>avatar-app</artifactId>
      <version>1.0-SNAPSHOT</version>
    
      <properties>
        <maven.compiler.target>17</maven.compiler.target>
        <maven.compiler.source>17</maven.compiler.source>
      </properties>
    
      <dependencies>
        <dependency>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>functions-framework-api</artifactId>
          <version>1.1.4</version>
        </dependency>
        <dependency>
          <groupId>com.google.code.gson</groupId>
          <artifactId>gson</artifactId>
          <version>2.9.1</version>
        </dependency>
        <dependency>
          <groupId>com.google.apis</groupId>
          <artifactId>google-api-services-chat</artifactId>
          <version>v1-rev20230115-2.0.0</version>
        </dependency>
      </dependencies>
    
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
            <excludes>
              <exclude>.google/</exclude>
            </excludes>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </project>
    1. Kliknij Zapisz i wdroż ponownie.

Otworzy się strona szczegółów usługi Cloud Run. Poczekaj na wdrożenie funkcji.

Konfigurowanie dodatku

Po wdrożeniu funkcji Cloud Run wykonaj te czynności, aby utworzyć dodatek i wdrożyć aplikację Google Chat:

  1. W konsoli Google Cloud otwórz stronę Cloud Run:

    Otwórz Cloud Run

    Sprawdź, czy wybrany jest projekt, w którym włączono Cloud Run.

  2. Na liście funkcji kliknij addonchatapp.

  3. Na stronie Szczegóły usługi skopiuj adres URL funkcji. Adres URL kończy się na run.app.

  4. W polu wyszukiwania Google Cloud wyszukaj „Google Chat API”, a następnie kliknij Google Chat API i Zarządzaj.

    Otwórz Chat API

  5. Kliknij Konfiguracja i skonfiguruj aplikację Google Chat:

    1. W polu Nazwa aplikacji wpisz Add-on Chat app.
    2. W polu URL awatara wpisz https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
    3. W polu Opis wpisz Add-on Chat app.
    4. W sekcji Funkcje wybierz Dołączanie do pokoi i rozmów grupowych.
    5. W sekcji Ustawienia połączenia kliknij URL punktu końcowego HTTP.
    6. Skopiuj adres e-mail konta usługi. Będziesz go potrzebować, gdy będziesz autoryzować dodatek do wywoływania funkcji.
    7. W sekcji Aktywatory kliknij Używaj wspólnego adresu URL punktu końcowego HTTP dla wszystkich aktywatorów i wklej adres URL aktywatora funkcji Cloud Run w odpowiednim polu.
    8. W sekcji Widoczność wybierz Udostępnij tę aplikację do obsługi czatu Google konkretnym osobom i grupom w domenie i wpisz swój adres e-mail.
    9. W sekcji Logi wybierz Loguj błędy w usłudze Logging.
  6. Kliknij Zapisz.

Następnie autoryzuj aplikację do obsługi czatu, aby wywoływała funkcję Cloud Run.

Autoryzowanie Google Chat do wywoływania funkcji

Aby autoryzować dodatek Google Workspace do wywoływania funkcji, dodaj konto usługi dodatku Google Workspace z rolą Wywołujący usługę Cloud Run.

  1. W konsoli Google Cloud otwórz stronę Cloud Run:

    Otwórz Cloud Run

  2. Na liście usług Cloud Run zaznacz pole wyboru obok funkcji receiving. (Nie klikaj samej funkcji).

  3. Kliknij Uprawnienia. Otworzy się panel Uprawnienia.

  4. Kliknij Dodaj podmiot zabezpieczeń.

  5. W polu Nowe podmioty zabezpieczeń wpisz adres e-mail konta usługi dodatku Google Workspace powiązanego z aplikacją Chat.

    Adres e-mail konta usługi znajdziesz na stronie konfiguracji interfejsu Chat API w sekcji Ustawienia połączenia > Adres URL punktu końcowego HTTP > Adres e-mail konta usługi:

    Otwórz konfigurację interfejsu Chat API

  6. W sekcji Wybierz rolę kliknij Cloud Run > Wywołujący usługę Cloud Run.

  7. Kliknij Zapisz.

Aplikacja Chat jest gotowa do odbierania wiadomości i odpowiadania na nie.

Testowanie aplikacji w Google Chat

Aby przetestować aplikację do Google Chat, otwórz czat z aplikacją i wyślij wiadomość:

  1. Otwórz Google Chat, korzystając z konta Google Workspace, które zostało podane podczas dodawania siebie jako zaufanego testera.

    Otwórz Google Chat

  2. Kliknij  Nowy czat.
  3. W polu Dodaj co najmniej 1 osobę wpisz nazwę aplikacji Chat.
  4. Wybierz aplikację Chat z wyników. Otworzy się czat.

  5. Na nowym czacie z aplikacją wpisz Hello i naciśnij enter.

Wiadomość w aplikacji Google Chat zawiera kartę z nazwą nadawcy i jego awatarem, jak pokazano na tym obrazie:

Aplikacja do obsługi czatu odpowiada kartą z wyświetlaną nazwą nadawcy i obrazem awatara.

Aby dodać zaufanych testerów i dowiedzieć się więcej o testowaniu funkcji interaktywnych, przeczytaj artykuł Testowanie funkcji interaktywnych w aplikacjach Google Chat.

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub karta zwraca błąd, interfejs Google Chat wyświetla komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs Google Chat nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta Google Chat daje nieoczekiwany wynik, np. wiadomość na karcie może się nie pojawić.

Chociaż w interfejsie czatu może nie wyświetlać się komunikat o błędzie, opisowe komunikaty o błędach i dane logowania są dostępne, aby pomóc w naprawieniu błędów, gdy rejestrowanie błędów w aplikacjach na czat jest włączone. Pomoc dotyczącą wyświetlania, debugowania i naprawiania błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat.

Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym samouczku, zalecamy usunięcie projektu w Cloud.

  1. W konsoli Google Cloud otwórz stronę Zarządzanie zasobami. Kliknij Menu > Administracja > Zarządzaj zasobami.

    Otwórz Menedżera zasobów

  2. Z listy projektów wybierz projekt do usunięcia, a potem kliknij Usuń .
  3. W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.