Tworzenie aplikacji HTTP Google Chat za pomocą Cloud Functions

Z tego artykułu dowiesz się, jak utworzyć aplikację do obsługi czatu HTTP. Istnieją różne sposoby wdrażania tej architektury. W Google Cloud można korzystać z Cloud Functions, Cloud Run i App Engine. W tym krótkim wprowadzeniu utworzysz i wdrożysz funkcję w Cloud Functions, której aplikacja Google Chat używa do odpowiadania na wiadomość użytkownika.

W przypadku tej architektury konfigurujesz Google Chat do integracji z Google Cloud lub serwerem lokalnym za pomocą protokołu HTTP, jak pokazano na tym diagramie:

Na poprzednim diagramie użytkownik wchodzący w interakcję z aplikacją HTTP do obsługi czatu ma następujący przepływ informacji:

1. Użytkownik wysyła wiadomość z Google Chat do aplikacji Google Chat na czacie lub w pokoju czatu.
2. Żądanie HTTP jest wysyłane do serwera WWW działającego w chmurze lub przez system lokalny zawierający logikę aplikacji Google Chat.
3. Opcjonalnie logika aplikacji Google Chat może integrować się z usługami Google Workspace (takimi jak Kalendarz i Arkusze), innymi usługami Google (np. Mapami, YouTube czy Vertex AI) lub innymi usługami internetowymi (np. systemem zarządzania projektami lub narzędziem do sprzedaży biletów).
4. Serwer WWW wysyła odpowiedź HTTP z powrotem do usługi aplikacji Google Chat w Google Chat.
5. Odpowiedź jest dostarczana do użytkownika.
6. Opcjonalnie aplikacja Google Chat może wywołać interfejs Chat API, aby asynchronicznie publikować wiadomości lub wykonywać inne operacje.

Ta architektura zapewnia elastyczność korzystania z istniejących bibliotek i komponentów, które już istnieją w systemie, ponieważ aplikacje do obsługi czatu 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.
• Przetestuj aplikację.

Wymagania wstępne

• Konto Google Workspace z dostępem do Google Chat i Google Cloud Functions.
• Projekt Google Cloud –
• Sprawdź, czy masz włączone płatności w projekcie Cloud. Dowiedz się, jak sprawdzić stan płatności za projekty.

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łączanie interfejsów 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ą nadawcy i awatarem. Gdy aplikacja Google Chat otrzyma wiadomość, uruchamia funkcję i odpowiada za pomocą karty.

Aby utworzyć i wdrożyć funkcję aplikacji Google 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 Google Chat.

2. Kliknij Utwórz funkcję.

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

   1. W sekcji Środowisko wybierz 2 generacji.
   2. W polu Nazwa funkcji wpisz QuickStartChatApp.
   3. W polu Region wybierz region.
   4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelnienia.
   5. Kliknij Dalej.

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

5. W sekcji Source code (Kod źródłowy) wybierz Wbudowany edytor.

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

7. Zastąp zawartość pola index.js tym kodem:

   node/avatar-app/index.js

   Wyświetl w GitHubie

   /**
    * Google Cloud Function that responds to messages sent from a
    * Google Chat room.
    *
    * @param {Object} req Request sent from Google Chat room
    * @param {Object} res Response to send back
    */
   exports.helloChat = function helloChat(req, res) {
     if (req.method === 'GET' || !req.body.message) {
       res.send('Hello! This function is meant to be used in a Google Chat ' +
         'Room.');
     }
   
     const sender = req.body.message.sender.displayName;
     const image = req.body.message.sender.avatarUrl;
   
     const data = createMessage(sender, image);
   
     res.send(data);
   };
   
   /**
    * Creates a card with two widgets.
    * @param {string} displayName the sender's display name
    * @param {string} imageUrl the URL for the sender's avatar
    * @return {Object} a card with the user's avatar.
    */
   function createMessage(displayName, imageUrl) {
     const cardHeader = {
       title: `Hello ${displayName}!`,
     };
   
     const avatarWidget = {
       textParagraph: {text: 'Your avatar picture: '},
     };
   
     const avatarImageWidget = {
       image: {imageUrl},
     };
   
     const avatarSection = {
       widgets: [
         avatarWidget,
         avatarImageWidget,
       ],
     };
   
     return {
       text: 'Here\'s your avatar',
       cardsV2: [{
         cardId: 'avatarCard',
         card: {
           name: 'Avatar Card',
           header: cardHeader,
           sections: [avatarSection],
         }
       }],
     };
   }

8. Kliknij Wdróż.

Python

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

   Otwórz Cloud Functions

   Sprawdź, czy wybrany jest projekt aplikacji Google Chat.

2. Kliknij Utwórz funkcję.

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

   1. W sekcji Środowisko wybierz 2 generacji.
   2. W polu Nazwa funkcji wpisz QuickStartChatApp.
   3. W polu Region wybierz region.
   4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelnienia.
   5. Kliknij Dalej.

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

5. W sekcji Source code (Kod źródłowy) wybierz Wbudowany edytor.

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

7. Zastąp zawartość pola main.py tym kodem:

   python/avatar-app/main.py

   Wyświetl w GitHubie

   from typing import Any, Mapping
   
   import flask
   import functions_framework
   
   
   # Google Cloud Function that responds to messages sent in
   # Google Chat.
   #
   # @param {Object} req Request sent from Google Chat.
   # @param {Object} res Response to send back.
   @functions_framework.http
   def hello_chat(req: flask.Request) -> Mapping[str, Any]:
     if req.method == "GET":
       return "Hello! This function must be called from Google Chat."
   
     request_json = req.get_json(silent=True)
   
     display_name = request_json["message"]["sender"]["displayName"]
     avatar = request_json["message"]["sender"]["avatarUrl"]
   
     response = create_message(name=display_name, image_url=avatar)
   
     return response
   
   
   # Creates a card with two widgets.
   # @param {string} name the sender's display name.
   # @param {string} image_url the URL for the sender's avatar.
   # @return {Object} a card with the user's avatar.
   def create_message(name: str, image_url: str) -> Mapping[str, Any]:
     avatar_image_widget = {"image": {"imageUrl": image_url}}
     avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
     avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}
   
     header = {"title": f"Hello {name}!"}
   
     cards = {
         "text": "Here's your avatar",
         "cardsV2": [
             {
                 "cardId": "avatarCard",
                 "card": {
                     "name": "Avatar Card",
                     "header": header,
                     "sections": [avatar_section],
                 },
             }
         ]
     }
   
     return cards

8. Kliknij Wdróż.

Java

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

   Otwórz Cloud Functions

   Sprawdź, czy wybrany jest projekt aplikacji Google Chat.

2. Kliknij Utwórz funkcję.

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

   1. W sekcji Środowisko wybierz 2 generacji.
   2. W polu Nazwa funkcji wpisz QuickStartChatApp.
   3. W polu Region wybierz region.
   4. W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelnienia.
   5. Kliknij Dalej.

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

5. W sekcji Source code (Kod źródłowy) wybierz Wbudowany edytor.

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

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

8. Zastąp zawartość pola HelloChat.java tym kodem:

   java/avatar-app/src/main/java/HelloChat.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.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 HelloChat implements HttpFunction {
     private static final Gson gson = new Gson();
   
     @Override
     public void service(HttpRequest request, HttpResponse response) throws Exception {
       JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);
   
       if (request.getMethod().equals("GET") || !body.has("message")) {
         response.getWriter().write("Hello! This function must be called from Google Chat.");
         return;
       }
   
       JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
       String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
       String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
       Message message = createMessage(displayName, avatarUrl);
   
       response.getWriter().write(gson.toJson(message));
     }
   
     Message createMessage(String displayName, String avatarUrl) {
       GoogleAppsCardV1CardHeader cardHeader = new GoogleAppsCardV1CardHeader();
       cardHeader.setTitle(String.format("Hello %s!", displayName));
   
       GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
       textParagraph.setText("Your avatar picture: ");
   
       GoogleAppsCardV1Widget avatarWidget = new GoogleAppsCardV1Widget();
       avatarWidget.setTextParagraph(textParagraph);
   
       GoogleAppsCardV1Image image = new GoogleAppsCardV1Image();
       image.setImageUrl(avatarUrl);
   
       GoogleAppsCardV1Widget avatarImageWidget = new GoogleAppsCardV1Widget();
       avatarImageWidget.setImage(image);
   
       GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
       section.setWidgets(List.of(avatarWidget, avatarImageWidget));
   
       GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
       card.setName("Avatar Card");
       card.setHeader(cardHeader);
       card.setSections(List.of(section));
   
       CardWithId cardWithId = new CardWithId();
       cardWithId.setCardId("previewLink");
       cardWithId.setCard(card);
   
       Message message = new Message();
       message.setText("Here's your avatar");
       message.setCardsV2(List.of(cardWithId));
   
       return message;
     }
   }

9. Zastąp zawartość pola pom.xml tym kodem:

   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/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>cloudfunctions</groupId>
     <artifactId>http-function</artifactId>
     <version>1.0-SNAPSHOT</version>
   
     <properties>
       <maven.compiler.target>11</maven.compiler.target>
       <maven.compiler.source>11</maven.compiler.source>
     </properties>
   
     <dependencies>
       <dependency>
         <groupId>com.google.cloud.functions</groupId>
         <artifactId>functions-framework-api</artifactId>
         <version>1.0.1</version>
       </dependency>
   
       <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
       <dependency>
           <groupId>com.google.code.gson</groupId>
           <artifactId>gson</artifactId>
           <version>2.9.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-rev20230115-2.0.0</version>
       </dependency>
     </dependencies>
   
     <!-- Required for Java 11 functions in the inline editor -->
     <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>

10. Kliknij Wdróż.

Otworzy się strona z informacjami o funkcji w Cloud Functions, a w jej miejsce widoczne będą 2 wskaźniki postępu: jeden dla kompilacji i jeden dla usługi. Gdy oba wskaźniki postępu znikają i zastępują znacznik wyboru, funkcja jest wdrożona i gotowa.

Autoryzuj 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 odbierającej. Nie klikaj samej funkcji.

3. Kliknij Uprawnienia. Otworzy się panel Uprawnienia.

4. Kliknij Dodaj podmiot zabezpieczeń.

5. W sekcji Nowe podmioty zabezpieczeń wpisz [e-mail].

6. W sekcji Wybierz rolę kliknij 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

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

2. Na liście funkcji kliknij QuickStartChatApp.

3. Kliknij kartę Reguły.

4. Skopiuj adres URL w polu HTTPS.

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

   Przejdź do interfejsu 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 Funkcjonalność wybierz Odbieranie wiadomości 1:1 i Dołączanie do pokoi i rozmów grupowych.
   5. W sekcji Ustawienia połączenia wybierz URL aplikacji i wklej w polu adres URL aktywatora funkcji w Cloud Functions.
   6. W sekcji Authentication Audience (Odbiorcy uwierzytelniania) wybierz App URL (Adres URL aplikacji).
   7. W sekcji Widoczność wybierz Udostępnij tę aplikację Google Chat określonym osobom i grupom w domenie, a następnie wpisz swój adres e-mail.
   8. W sekcji Logi wybierz Rejestruj błędy w usłudze Logging.

7. Kliknij Zapisz.

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

Testowanie aplikacji Google Chat

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

1. Otwórz Google Chat za pomocą konta Google Workspace podanego podczas dodawania Ciebie 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. Z wyników wybierz aplikację Google Chat. Otworzy się czat.

   Uwaga: jeśli nie widzisz swojej aplikacji Google Chat 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 konsoli Google Cloud.
5. W nowym czacie z aplikacją wpisz Hello i naciśnij enter.

Odpowiedź aplikacji Google Chat zawiera wiadomość na karcie z nazwą nadawcy i awatarem, jak pokazano na tym 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 lub karta w Google Chat zwróci błąd, w interfejsie Google Chat pojawi się komunikat „Coś poszło nie tak”. lub „Nie można przetworzyć żądania”. Czasami w UI Google Chat nie wyświetla się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład wiadomość na karcie.

Mimo że komunikat o błędzie może nie być wyświetlany w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane logów, które pomogą Ci w naprawianiu błędów, gdy logowanie błędów w aplikacjach Google Chat jest włączone. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami w Google Chat.

Czyszczenie danych

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

Uwaga: usunięcie projektu spowoduje, że:

• Wszystkie dane projektu zostaną usunięte. Jeśli w tym samouczku był używany istniejący projekt, usunięcie go spowoduje też usunięcie wszystkich innych zadań wykonanych w tym projekcie.
• Niestandardowe identyfikatory projektu zostaną utracone. Być może w trakcie tworzenia tego projektu został utworzony niestandardowy identyfikator projektu, którego chcesz używać w przyszłości. Aby zachować adresy URL, które używają identyfikatora projektu, na przykład adres URL na appspot.com, usuń wybrane zasoby w projekcie, zamiast usuwać cały projekt.

Jeśli planujesz skorzystać z wielu samouczków i krótkich wprowadzeń, ponowne wykorzystanie tych samych projektów może pomóc Ci uniknąć przekroczenia limitów projektów.

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 do usunięcia, a następnie 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 wiadomości na kartach interaktywnych
  • Reagowanie na polecenia po ukośniku
  • Otwieranie okien i odpowiadanie na nie

• Wybieranie architektury aplikacji do obsługi czatu

• Weryfikowanie próśb z Google Chat