Na tej stronie znajdziesz instrukcje tworzenia dodatku do Google Workspace, który działa w Google Chat przy użyciu usługi HTTP. W Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Więcej informacji znajdziesz w artykule Więcej informacji o rozszerzaniu Google Chat.
Z tego krótkiego wprowadzenia dowiesz się, jak utworzyć usługę HTTP za pomocą usług Google Cloud. Aby utworzyć aplikację Google Chat, piszesz i wdrażasz funkcję w Cloud Functions, której aplikacja Google Chat używa do odpowiadania na wiadomości użytkownika.
W przypadku architektury HTTP konfigurujesz integrację Google Chat z Google Cloud lub serwerem lokalnym za pomocą HTTP, jak pokazano na poniższym diagramie:
Na powyższym diagramie użytkownik korzystający z aplikacji HTTPChat ma następujący przepływ informacji:
- Użytkownik wysyła wiadomość w Google Chat do aplikacji Google Chat, w wiadomości bezpośredniej lub w pokoju Google Chat.
- Żądanie HTTP jest wysyłane do serwera WWW, który jest systemem chmurowym lub lokalnym zawierającym logikę aplikacji Google Chat.
- 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ń).
- Serwer WWW wysyła odpowiedź HTTP z powrotem do usługi aplikacji Google Chat w Google Chat.
- Odpowiedź jest następnie wyświetlana użytkownikowi.
- 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.
- Skonfiguruj dodatek Google Workspace dla aplikacji 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.
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
W konsoli Google Cloud otwórz stronę Cloud Functions:
Sprawdź, czy wybrany jest projekt aplikacji Chat.
Kliknij
Utwórz funkcję.Na stronie Utwórz funkcję skonfiguruj funkcję:
- W sekcji Środowisko wybierz Funkcja Cloud Run.
- W polu Nazwa funkcji wpisz
AddOnChatApp
. - W polu Region wybierz region.
- W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
- Kliknij Dalej.
W sekcji Środowisko wykonawcze wybierz najnowszą wersję Node.js.
W sekcji Kod źródłowy wybierz Edytor wbudowany.
W polu Punkt wejścia usuń tekst domyślny i wpisz
avatarApp
.Zamień zawartość pliku
index.js
na ten kod:/** * Google Cloud Function that responds to messages sent from a * Google Chat space. * * @param {Object} req Request sent from Google Chat space * @param {Object} res Response to send back */ exports.avatarApp = function avatarApp(req, res) { if (req.method === 'GET' || !req.body.chat) { return res.send('Hello! This function is meant to be used ' + 'in a Google Chat Space.'); } // Stores the Google Chat event as a variable. const chatMessage = req.body.chat.messagePayload.message; // Replies with the sender's avatar in a card. const displayName = chatMessage.sender.displayName; const avatarUrl = chatMessage.sender.avatarUrl; res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: { 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 } }] }] } }] }}}}}); };
Kliknij Wdróż.
Python
W konsoli Google Cloud otwórz stronę Cloud Functions:
Sprawdź, czy wybrany jest projekt aplikacji Chat.
Kliknij
Utwórz funkcję.Na stronie Utwórz funkcję skonfiguruj funkcję:
- W sekcji Środowisko wybierz Funkcja Cloud Run.
- W polu Nazwa funkcji wpisz
AddOnChatApp
. - W polu Region wybierz region.
- W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
- Kliknij Dalej.
W sekcji Środowisko wykonawcze wybierz najnowszą wersję Pythona.
W sekcji Kod źródłowy wybierz Edytor wbudowany.
W polu Punkt wejścia usuń tekst domyślny i wpisz
avatar_app
.Zamień zawartość pliku
main.py
na ten kod:from typing import Any, Mapping import flask import functions_framework @functions_framework.http def avatar_app(req: flask.Request) -> Mapping[str, Any]: """Google Cloud Function that handles requests from Google Chat Args: flask.Request: the request Returns: Mapping[str, Any]: the response """ if req.method == "GET": return "Hello! This function must be called from Google Chat." request_json = req.get_json(silent=True) # Stores the Google Chat event as a variable. chat_message = request_json["chat"]["messagePayload"]["message"] # Replies with the sender's avatar in a card. display_name = chat_message["sender"]["displayName"] avatar_url = chat_message["sender"]["avatarUrl"] return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": { "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 } }] }] } }] }}}}}
Kliknij Wdróż.
Java
W konsoli Google Cloud otwórz stronę Cloud Functions:
Sprawdź, czy wybrany jest projekt aplikacji Chat.
Kliknij
Utwórz funkcję.Na stronie Utwórz funkcję skonfiguruj funkcję:
- W sekcji Środowisko wybierz Funkcja Cloud Run.
- W polu Nazwa funkcji wpisz
AddOnChatApp
. - W polu Region wybierz region.
- W sekcji Uwierzytelnianie wybierz Wymagaj uwierzytelniania.
- Kliknij Dalej.
W sekcji Środowisko wykonawcze wybierz najnowszą wersję Java.
W sekcji Kod źródłowy wybierz Edytor wbudowany.
W polu Punkt wejścia usuń tekst domyślny i wpisz
AvatarApp
.Zmień nazwę domyślnego pliku Java na
src/main/java/AvatarApp.java
.Zamień zawartość pliku
AvatarApp.java
na ten kod:import java.util.List; 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; public class AvatarApp 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("chat")) { response.getWriter().write("Hello! This function is meant to be used " + "in a Google Chat Space.."); return; } // Stores the Google Chat event as a variable. JsonObject chatMessage = body.getAsJsonObject("chat") .getAsJsonObject("messagePayload").getAsJsonObject("message"); // Replies with the sender's avatar in a card. String displayName = chatMessage.getAsJsonObject("sender").get("displayName").getAsString(); String avatarUrl = chatMessage.getAsJsonObject("sender").get("avatarUrl").getAsString(); Message message = createMessage(displayName, avatarUrl); 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)); } 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("avatarCard"); cardWithId.setCard(card); Message message = new Message(); message.setText("Here's your avatar"); message.setCardsV2(List.of(cardWithId)); return message; } }
Zamień zawartość pliku
pom.xml
na ten kod:<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.0.4</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 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>
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ć dodatek Google Workspace do wywoływania funkcji, dodaj konto usługi dodatku Google Workspace z rolą Cloud Run Invoker.
W konsoli Google Cloud otwórz stronę Cloud Run:
Na liście usług Cloud Run zaznacz pole wyboru obok funkcji odbierającej. (Nie klikaj samej funkcji).
Kliknij Uprawnienia. Otworzy się panel Uprawnienia.
Kliknij Dodaj podmiot zabezpieczeń.
W polu Nowe podmioty zabezpieczeń wpisz adres e-mail konta usługi dodatku Google Workspace powiązanego z Twoim projektem.
W sekcji Wybierz rolę wybierz Cloud Run > Wywołujący Cloud Run.
Kliknij Zapisz.
Konfigurowanie dodatku
Po wdrożeniu funkcji w Cloud Functions wykonaj te czynności, aby utworzyć dodatek i wdrożyć aplikację Google Chat:
W konsoli Google Cloud kliknij Menu > Cloud Functions.
Upewnij się, że wybrany jest projekt, w którym włączono Cloud Functions.
Na liście funkcji kliknij AddOnChatApp.
Kliknij kartę Reguły.
W sekcji HTTPS skopiuj adres URL.
Wyszukaj „Google Chat API” i kliknij Google Chat API, a potem kliknij Zarządzaj.
Kliknij Konfiguracja i skonfiguruj aplikację Google Chat:
- W polu Nazwa aplikacji wpisz
Add-on Chat app
. - W polu URL awatara wpisz
https://developers.google.com/chat/images/quickstart-app-avatar.png
. - W polu Opis wpisz
Add-on Chat app
. - W sekcji Funkcje wybierz Odbieranie wiadomości 1:1 i Dołączanie do pokoi i rozmów grupowych.
- W sekcji Ustawienia połączenia kliknij Adres URL punktu końcowego HTTP i wklej w tym polu adres URL reguły Cloud Functions.
- W sekcji Authentication Audience (Odbiorcy uwierzytelniania) wybierz URL punktu końcowego HTTP.
- W sekcji Widoczność wybierz Udostępnij tę aplikację Google Chat konkretnym osobom i grupom w swojej domenie i wpisz swój adres e-mail.
- W sekcji Logi wybierz Loguj błędy w usłudze Logging.
- W polu Nazwa aplikacji wpisz
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ść:
Otwórz Google Chat za pomocą konta Google Workspace, które zostało podane podczas dodawania siebie jako zaufanego testera.
- Kliknij Nowy czat.
- W polu Dodaj co najmniej 1 osobę wpisz nazwę aplikacji Google Chat.
Wybierz aplikację Google Chat z wyników. Otworzy się czat.
- W nowym czacie z aplikacją wpisz
Hello
i naciśnijenter
.
Wiadomość w aplikacji Google Chat zawiera kartę z nazwą nadawcy i jego obrazem awatara, jak widać 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, 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.
- W konsoli Google Cloud otwórz stronę Zarządzanie zasobami. Kliknij Menu > Administracja > Zarządzaj zasobami.
- Na liście projektów wybierz projekt, który chcesz usunąć, a potem kliknij Usuń .
- W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.