Tworzenie aplikacji HTTP Google Chat

Uwaga: ten przewodnik wyjaśnia, jak utworzyć interaktywną aplikację do obsługi czatu za pomocą zdarzeń interakcji interfejsu Chat API. Aplikację do czatu możesz też utworzyć jako dodatek do Google Workspace. Więcej informacji o tym, którego frameworka użyć, znajdziesz w artykule Tworzenie interaktywnej aplikacji Google Chat.

Na tej stronie dowiesz się, jak utworzyć aplikację do czatu HTTP. Istnieją różne sposoby wdrożenia tej architektury. W Google Cloud możesz używać Cloud Run i App Engine. Z tego krótkiego wprowadzenia dowiesz się, jak napisać i wdrożyć funkcję Cloud Run, której aplikacja Google Chat używa do odpowiadania na wiadomości użytkowników.

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

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, na czacie 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 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.
• Opublikuj aplikację w Google Chat.
• Przetestuj aplikację.

Wymagania wstępne

• Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
• Projekt Google Cloud z włączonymi płatnościami. Aby sprawdzić, czy w istniejącym projekcie włączone są płatności, przeczytaj artykuł Sprawdzanie stanu płatności w projektach. Aby utworzyć projekt i skonfigurować rozliczenia, przeczytaj artykuł Tworzenie projektu Google Cloud.

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 Google Chat API, 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 quickstartchatapp.
   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. Zamień zawartość pliku index.js na taki kod:

      node/avatar-app/index.js

      Wyświetl w GitHubie
      const functions = require('@google-cloud/functions-framework');
      
      // Command IDs (configure these in Google Chat API)
      const ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
      const HELP_COMMAND_ID = 2; // ID for the "Help" quick command
      
      /**
       * Google Cloud Function that handles HTTP requests from Google Chat.
       *
       * @param {Object} req - The HTTP request object sent from Google Chat.
       * @param {Object} res - The HTTP response object.
       */
      functions.http('avatarApp', (req, res) => {
        const event = req.body;
      
        if (event.appCommandMetadata) {
          handleAppCommands(event, res);
        } else {
          handleRegularMessage(event, res);
        }
      });
      
      /**
       * Handles slash and quick commands.
       *
       * @param {Object} event - The Google Chat event.
       * @param {Object} res - The HTTP response object.
       */
      function handleAppCommands(event, res) {
        const {appCommandId, appCommandType} = event.appCommandMetadata;
      
        switch (appCommandId) {
          case ABOUT_COMMAND_ID:
            return res.send({
              privateMessageViewer: event.user,
              text: 'The Avatar app replies to Google Chat messages.'
            });
          case HELP_COMMAND_ID:
            return res.send({
              privateMessageViewer: event.user,
              text: 'The Avatar app replies to Google Chat messages.'
            });
        }
      }
      
      /**
       * Handles regular messages (not commands).
       *
       * @param {Object} event - The Google Chat event.
       * @param {Object} res - The HTTP response object.
       */
      function handleRegularMessage(event, res) {
        const messageData = createMessage(event.user);
        res.send(messageData);
      }
      
      /**
       * Creates a card message with the user's avatar.
       *
       * @param {Object} user - The user who sent the message.
       * @param {string} user.displayName - The user's display name.
       * @param {string} user.avatarUrl - The URL of the user's avatar.
       * @return {Object} - The card message object.
       */
      function createMessage({displayName, 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}},
                ],
              }],
            },
          }],
        };
      }

   3. 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 quickstartchatapp.
   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. Zamień zawartość pliku main.py na taki kod:

      python/avatar-app/main.py

      Wyświetl w GitHubie
      from typing import Any, Mapping
      
      import flask
      import functions_framework
      
      # Command IDs (configure these in Google Chat API)
      ABOUT_COMMAND_ID = 1  # ID for the "/about" slash command
      HELP_COMMAND_ID = 2  # ID for the "Help" quick command
      
      
      @functions_framework.http
      def avatar_app(req: flask.Request) -> Mapping[str, Any]:
          """Google Cloud Function that handles HTTP requests from Google Chat.
      
          Args:
              flask.Request: the request
      
          Returns:
              Mapping[str, Any]: the response
          """
          event = req.get_json(silent=True)
      
          if event and "appCommandMetadata" in event:
              return handle_app_commands(event)
          else:
              return handle_regular_message(event)
      
      
      def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
          """Handles slash and quick commands.
      
          Args:
              Mapping[str, Any] event: The Google Chat event.
      
          Returns:
              Mapping[str, Any]: the response
          """
          app_command_id = event["appCommandMetadata"]["appCommandId"]
      
          if app_command_id == ABOUT_COMMAND_ID:
              return {
                  "privateMessageViewer": event["user"],
                  "text": "The Avatar app replies to Google Chat messages.",
              }
          elif app_command_id == HELP_COMMAND_ID:
              return {
                  "privateMessageViewer": event["user"],
                  "text": "The Avatar app replies to Google Chat messages.",
              }
          return {}
      
      
      
      
      def handle_regular_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
          """Handles regular messages (not commands).
      
          Args:
              Mapping[str, Any] event: The Google Chat event.
      
          Returns:
              Mapping[str, Any]: the response
          """
      
          if not event or "user" not in event:
              return "Invalid request."
      
          message_data = create_message(event["user"])
          return message_data
      
      
      def create_message(user: Mapping[str, Any]) -> Mapping[str, Any]:
          """Creates a card message with the user's avatar.
      
          Args:
              Mapping[str, Any] user: The user who sent the message.
      
          Returns:
              Mapping[str, Any]: a card with the user's avatar.
          """
          display_name = user.get("displayName", "")
          avatar_url = 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}},
                                  ]
                              }
                          ],
                      },
                  }
              ],
          }

   3. 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 quickstartchatapp.
   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ę src/main/java/com/example/Example.java na src/main/java/AvatarApp.java.

   3. Zamień zawartość pliku AvatarApp.java na taki kod:

      java/avatar-app/src/main/java/AvatarApp.java

      Wyświetl w GitHubie
      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.api.services.chat.v1.model.User;
      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 AvatarApp implements HttpFunction {
        private static final Gson gson = new Gson();
      
        // Command IDs (configure these in Google Chat API)
        private static final int ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
        private static final int HELP_COMMAND_ID = 2; // ID for the "Help" quick command
      
        @Override
        public void service(HttpRequest request, HttpResponse response) throws Exception {
          JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
      
          if (event.has("appCommandMetadata")) {
            handleAppCommands(event, response);
          } else {
            handleRegularMessage(event, response);
          }
        }
      
        /**
         * Handles slash and quick commands.
         *
         * @param event    The Google Chat event.
         * @param response The HTTP response object.
         */
        private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
          int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();
      
          switch (appCommandId) {
            case ABOUT_COMMAND_ID:
              Message aboutMessage = new Message();
              aboutMessage.setText("The Avatar app replies to Google Chat messages.");
              aboutMessage.setPrivateMessageViewer(new User()
                  .setName(event.getAsJsonObject("user").get("name").getAsString()));
              response.getWriter().write(gson.toJson(aboutMessage));
              return;
            case HELP_COMMAND_ID:
              Message helpMessage = new Message();
              helpMessage.setText("The Avatar app replies to Google Chat messages.");
              helpMessage.setPrivateMessageViewer(new User()
                  .setName(event.getAsJsonObject("user").get("name").getAsString()));
              response.getWriter().write(gson.toJson(helpMessage));
              return;
          }
        }
      
        /**
         * Handles regular messages (not commands).
         *
         * @param event    The Google Chat event.
         * @param response The HTTP response object.
         */
        private void handleRegularMessage(JsonObject event, HttpResponse response) throws Exception {
      
          if (!event.has("user")) {
            response.getWriter().write("Invalid request.");
            return;
          }
      
          JsonObject user = event.getAsJsonObject("user");
          String displayName = user.has("displayName") ? user.get("displayName").getAsString() : "";
          String avatarUrl = user.has("avatarUrl") ? user.get("avatarUrl").getAsString() : "";
          Message message = createMessage(displayName, avatarUrl);
          response.getWriter().write(gson.toJson(message));
        }
      
        /**
         * Creates a card message with the user's avatar.
         *
         * @param displayName The user's display name.
         * @param avatarUrl   The URL of the user's avatar.
         * @return The card message object.
         */
        private Message createMessage(String displayName, String avatarUrl) {
          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)))))))));
        }
      }

   4. Zamień zawartość pliku pom.xml na taki kod:

      java/avatar-app/pom.xml

      Wyświetl w GitHubie
      <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/maven-v4_0_0.xsd">
        <modelVersion>4.0.0</modelVersion>
      
        <groupId>gcfv2</groupId>
        <artifactId>avatar-app</artifactId>
        <version>0.0.1</version>
        <name>Avatar App</name>
      
        <properties>
          <maven.compiler.release>21</maven.compiler.release>
        </properties>
      
        <dependencies>
          <dependency>
            <groupId>com.google.cloud.functions</groupId>
            <artifactId>functions-framework-api</artifactId>
            <version>1.1.4</version>
          </dependency>
      
          <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
          <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.12.1</version>
          </dependency>
      
          <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->
          <dependency>
            <groupId>com.google.apis</groupId>
            <artifactId>google-api-services-chat</artifactId>
            <version>v1-rev20250116-2.0.0</version>
          </dependency>
      
        </dependencies>
      
      </project>

   5. Kliknij Zapisz i wdroż ponownie.

Autoryzowanie Google Chat do wywoływania funkcji

Aby autoryzować Google Chat do wywoływania funkcji, dodaj konto usługi Google Chat z rolą Wywołujący 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 [e-mail].

6. W sekcji Wybierz rolę wybierz Cloud Run > Wywołujący Cloud Run.

7. Kliknij Zapisz.

Konfigurowanie aplikacji Google Chat

Po wdrożeniu funkcji Cloud Run wykonaj te czynności, aby przekształcić ją w 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 usług kliknij quickstartchatapp.

3. Na stronie Szczegóły usługi skopiuj adres URL funkcji.

4. Wyszukaj „Google Chat API” i kliknij Google Chat API, a następnie Zarządzaj.

   Otwórz Chat API

5. Kliknij Konfiguracja i skonfiguruj aplikację Google Chat:

   1. Odznacz pole Utwórz tę aplikację do czatu jako dodatek do Google Workspace. Otworzy się okno z prośbą o potwierdzenie. W oknie dialogowym kliknij Wyłącz.
   2. W polu Nazwa aplikacji wpisz Quickstart App.
   3. W polu URL awatara wpisz https://developers.google.com/chat/images/quickstart-app-avatar.png.
   4. W polu Opis wpisz Quickstart app.
   5. W sekcji Funkcje wybierz Dołączanie do pokoi i rozmów grupowych.
   6. W sekcji Ustawienia połączenia wybierz URL punktu końcowego HTTP.
   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 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.

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

Testowanie aplikacji Google Chat

Aby przetestować aplikację do obsługi czatu, otwórz pokój czatu 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.

   Uwaga: jeśli nie widzisz swojej aplikacji do obsługi czatu na liście wyników, sprawdź, czy Twoje konto Google Workspace zostało uwzględnione w ustawieniach Widoczność na stronie Konfiguracja interfejsu Chat API w Google Cloud Console.
5. Na nowym czacie z aplikacją wpisz Hello i naciśnij enter.

Odpowiedź aplikacji Chat zawiera wiadomość w formie karty, która wyświetla nazwę nadawcy i obraz awatara, jak pokazano na poniższym obrazie:

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, w interfejsie Google Chat pojawia się 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.

Ostrzeżenie: usunięcie projektu spowoduje, że:

• Wszystkie dane projektu zostaną usunięte. Jeśli na potrzeby tego samouczka został przez Ciebie użyty istniejący projekt, po jego usunięciu usuniesz też wszystkie inne wykonane w nim zadania.
• Niestandardowe identyfikatory projektu zostaną utracone. Podczas tworzenia tego projektu możesz utworzyć niestandardowy identyfikator projektu, którego chcesz używać w przyszłości. Aby zachować adresy URL, które używają identyfikatora projektu, np. adres URL w domenie appspot.com, usuń wybrane zasoby w projekcie zamiast usuwać cały projekt.

Jeśli zamierzasz skorzystać z innych samouczków i krótkich wprowadzeń, ponowne wykorzystanie tych samych projektów może pomóc Ci uniknąć przekroczenia Iimitów związanych z projektami.

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.

Powiązane artykuły

• Aby dodać więcej funkcji do aplikacji Google Chat, zapoznaj się z tymi artykułami:

  • Tworzenie interaktywnych wiadomości w formie kart
  • Odpowiadanie na polecenia rozpoczynające się ukośnikiem
  • Otwieranie okien i odpowiadanie na pytania

• Wybieranie architektury aplikacji Google Chat

• Weryfikowanie próśb z Google Chat