Tworzenie aplikacji HTTP Google Chat

Z tej strony dowiesz się, jak utworzyć aplikację HTTP Chat. Architekturę tę można wdrażać na różne sposoby. W Google Cloud możesz używać Cloud Functions, Cloud Run i App Engine. W tym krótkim wprowadzeniu napiszesz i wdrożysz funkcję w Cloud Functions, której aplikacja Chat używa do odpowiadania na wiadomości użytkowników.

W tej architekturze konfigurujesz integrację Google Chat z Google Cloud lub serwerem lokalnym za pomocą HTTP, jak pokazano na poniższym schemacie:

Na powyższym diagramie użytkownik korzystający z aplikacji HTTPChat ma następujący przepływ informacji:

1. Użytkownik wysyła wiadomość w Google Chat do aplikacji Google Chat, w wiadomości bezpośredniej lub w pokoju Google Chat.
2. Żądanie HTTP jest wysyłane do serwera WWW, który jest systemem chmurowym lub lokalnym zawierającym logikę aplikacji Google Chat.
3. Opcjonalnie logika aplikacji Google Chat może zostać zintegrowana z usługami Google Workspace (np. Kalendarzem czy Arkuszami), innymi usługami Google (np. Mapami, YouTube czy Vertex AI) lub innymi usługami internetowymi (np. systemem zarządzania projektami czy narzędziem do obsługi zgłoszeń).
4. Serwer WWW wysyła odpowiedź HTTP z powrotem do usługi aplikacji Google Chat w Google Chat.
5. Odpowiedź jest następnie wyświetlana użytkownikowi.
6. Opcjonalnie aplikacja Google Chat może wywoływać interfejs Chat API, aby asynchronicznie publikować wiadomości lub wykonywać inne operacje.

Ta architektura zapewnia elastyczność w korzystaniu z dostępnych już w systemie bibliotek i komponentów, ponieważ aplikacje Google Chat można projektować w różnych językach programowania.

Cele

• skonfigurować środowisko,
• Utwórz i wdróż funkcję w Cloud Functions.
• Opublikuj aplikację w Google Chat.
• przetestować 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 są włączone płatności, zapoznaj się z artykułem Sprawdzanie stanu płatności w projektach. Aby utworzyć projekt i skonfigurować rozliczenia, zapoznaj się z artykułem Tworzenie projektu Google Cloud.

Konfigurowanie środowiska

Zanim zaczniesz korzystać z interfejsów API Google, musisz je włączyć w projekcie Google Cloud. W jednym projekcie Google Cloud możesz włączyć 1 lub więcej interfejsów 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łącz interfejsy API

Tworzenie i wdrażanie funkcji w Cloud Functions

Utwórz i wdróż funkcję w Cloud Functions, która generuje kartę czatu z wyświetlaną nazwą i obrazem awatara nadawcy. Gdy aplikacja Google Chat otrzyma wiadomość, wykona funkcję i wyświetli kartę.

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

Node.js

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

   Otwórz Cloud Functions

   Sprawdź, czy wybrany jest projekt aplikacji Chat.

2. Kliknij Utwórz funkcję.

3. Na stronie Utwórz funkcję skonfiguruj funkcję:

   1. W sekcji Środowisko wybierz Funkcja Cloud Run.
   2. W polu Nazwa funkcji wpisz QuickStartChatApp.
   3. W polu Region wybierz region.
   4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
   5. Kliknij Dalej.

4. W sekcji Środowisko wykonawcze wybierz najnowszą wersję Node.js.

5. W sekcji Kod źródłowy wybierz Edytor wbudowany.

6. W polu Punkt wejścia usuń tekst domyślny i wpisz avatarApp.

7. Zamień zawartość pliku index.js na ten 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}},
             ],
           }],
         },
       }],
     };
   }

8. Kliknij Wdróż.

Python

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

   Otwórz Cloud Functions

   Sprawdź, czy wybrany jest projekt aplikacji Chat.

2. Kliknij Utwórz funkcję.

3. Na stronie Utwórz funkcję skonfiguruj funkcję:

   1. W sekcji Środowisko wybierz Funkcja Cloud Run.
   2. W polu Nazwa funkcji wpisz QuickStartChatApp.
   3. W polu Region wybierz region.
   4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
   5. Kliknij Dalej.

4. W sekcji Środowisko wykonawcze wybierz najnowszą wersję Pythona.

5. W sekcji Kod źródłowy wybierz Edytor wbudowany.

6. W polu Punkt wejścia usuń tekst domyślny i wpisz avatar_app.

7. Zamień zawartość pliku main.py na ten 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}},
                               ]
                           }
                       ],
                   },
               }
           ],
       }

8. Kliknij Wdróż.

Java

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

   Otwórz Cloud Functions

   Sprawdź, czy wybrany jest projekt aplikacji Chat.

2. Kliknij Utwórz funkcję.

3. Na stronie Utwórz funkcję skonfiguruj funkcję:

   1. W sekcji Środowisko wybierz Funkcja Cloud Run.
   2. W polu Nazwa funkcji wpisz QuickStartChatApp.
   3. W polu Region wybierz region.
   4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
   5. Kliknij Dalej.

4. W sekcji Środowisko wykonawcze wybierz najnowszą wersję Java.

5. W sekcji Kod źródłowy wybierz Edytor wbudowany.

6. W polu Punkt wejścia usuń tekst domyślny i wpisz App.

7. Zmień nazwę src/main/java/com/example/Example.java na src/main/java/AvatarApp.java.

8. Zamień zawartość pliku AvatarApp.java na ten 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)))))))));
     }
   }

9. Zamień zawartość pliku pom.xml na ten 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>

10. Kliknij Wdróż.

Otworzy się strona z informacjami o Cloud Functions, na której zobaczysz swoją funkcję z 2 wskaźnikami postępu: jeden dla wersji, a drugi dla usługi. Gdy oba wskaźniki postępu znikną i zostanie zastąpione przez ikonę potwierdzenia, funkcja zostanie wdrożona i będzie gotowa do użycia.

Zezwalanie Google Chat na wywoływanie 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 odbierającej. (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.

Publikowanie aplikacji w Google Chat

Po wdrożeniu funkcji w Cloud Functions wykonaj te czynności, aby przekształcić ją w aplikację Google Chat:

1. W konsoli Google Cloud kliknij Menu > Cloud Functions.

   Otwórz Cloud Functions

   Upewnij się, że wybrany jest projekt, w którym włączono Cloud Functions.

2. Na liście funkcji kliknij QuickStartChatApp.

3. Kliknij kartę Reguły.

4. W sekcji HTTPS skopiuj adres URL.

5. Wyszukaj „Google Chat API” i kliknij Google Chat API, a potem kliknij Zarządzaj.

   Otwórz stronę Chat API

6. Kliknij Konfiguracja i skonfiguruj aplikację Google Chat:

   1. W polu Nazwa aplikacji wpisz Quickstart App.
   2. W polu URL awatara wpisz https://developers.google.com/chat/images/quickstart-app-avatar.png.
   3. W polu Opis wpisz Quickstart app.
   4. W sekcji Funkcje wybierz Odbieranie wiadomości 1:1 i Dołączanie do pokoi i rozmów grupowych.
   5. W sekcji Ustawienia połączenia kliknij Adres URL punktu końcowego HTTP i wklej w pole adres URL reguły aktywacji funkcji w chmurze.
   6. W sekcji Authentication Audience (Odbiorcy uwierzytelniania) wybierz URL punktu końcowego HTTP.
   7. W sekcji Widoczność wybierz Udostępnij tę aplikację Google Chat konkretnym osobom i grupom w swojej domenie i wpisz swój adres e-mail.
   8. W sekcji Logi wybierz Loguj błędy w usłudze Logging.

7. Kliknij Zapisz.

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

Testowanie aplikacji Google Chat

Aby przetestować aplikację Google Chat, otwórz czat w aplikacji Google Chat i wyślij wiadomość:

1. Otwórz Google Chat za pomocą 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 Google Chat.

4. Wybierz aplikację Google Chat z wyników. Otworzy się czat.

   Uwaga: jeśli nie widzisz aplikacji Google Chat na liście wyników, sprawdź, czy Twoje konto Google Workspace jest uwzględnione w ustawieniach widoczności na stronie Konfiguracja interfejsu Chat API w konsoli Google Cloud.
5. W nowym czacie z aplikacją wpisz Hello i naciśnij enter.

Odpowiedź aplikacji Google Chat zawiera wiadomość na karcie, w której widoczne są imię i nazwisko nadawcy oraz jego awatar, jak pokazano na poniższym obrazku:

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 czatu nie wyświetla żadnego komunikatu o błędzie, ale aplikacja Google Chat lub karta powoduje nieoczekiwany wynik, na przykład może nie wyświetlić się wiadomość na karcie.

Komunikat o błędzie może się nie wyświetlać w interfejsie czatu, ale gdy włączone jest rejestrowanie błędów w przypadku aplikacji czatu, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci je naprawić. Informacje o wyświetlaniu, debugowaniu i poprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami Google Chat.

Czyszczenie danych

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

Uwaga: usunięcie projektu spowoduje, że:

• Wszystkie dane projektu zostaną usunięte. Jeśli do tego samouczka został użyty istniejący projekt, jego usunięcie spowoduje również usunięcie wszystkich innych zadań w nim wykonanych.
• Niestandardowe identyfikatory projektu zostaną utracone. Podczas tworzenia tego projektu możesz utworzyć niestandardowy identyfikator projektu, którego chcesz użyć w przyszłości. Aby zachować adresy URL, które używają identyfikatora projektu, np. adres URL na 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. Na liście projektów wybierz projekt, który chcesz usunąć, 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, wykonaj te czynności:

  • Tworzenie interaktywnych wiadomości z kartą
  • Odpowiadanie na polecenia po ukośniku
  • Otwieranie i odpowiadanie na okna

• Wybieranie architektury aplikacji Google Chat

• Weryfikowanie żądań z Google Chat