Ta strona została przetłumaczona przez Cloud Translation API.

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:

Użytkownik wysyła wiadomość w Google Chat do aplikacji w Google Chat, na czacie lub w pokoju w Google Chat.
Żądanie HTTP jest wysyłane do serwera WWW, który jest systemem w chmurze lub systemem lokalnym zawierającym logikę aplikacji do obsługi Google Chat.
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ń).
Serwer WWW wysyła odpowiedź HTTP z powrotem do usługi aplikacji Chat w Google Chat.
Odpowiedź jest dostarczana do użytkownika.
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 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, zapoznaj się z artykułem 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 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

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

Otwórz Cloud Run

Sprawdź, czy wybrany jest projekt aplikacji do obsługi czatu.
Kliknij Napisz funkcję.
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.

Na karcie Źródło:

W polu Punkt wejścia usuń tekst domyślny i wpisz avatarApp.
Zamień zawartość pliku index.js na ten kod:

/**
 * Google Cloud Run 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
 */
import { http } from '@google-cloud/functions-framework';

http('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 }
                    }]
                }]
            }
        }]
    }}}}});
});

Zamień zawartość pliku package.json na ten kod:

{
  "name": "avatar-app",
  "version": "1.0.0",
  "description": "Google Chat Avatar App",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

Kliknij Zapisz i wdroż ponownie.

Python

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

Otwórz Cloud Run

Sprawdź, czy wybrany jest projekt aplikacji do obsługi czatu.
Kliknij Napisz funkcję.
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.

Na karcie Źródło:

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 Run 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 Zapisz i wdroż ponownie.

Java

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

Otwórz Cloud Run

Sprawdź, czy wybrany jest projekt aplikacji do obsługi czatu.
Kliknij Napisz funkcję.
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.

Na karcie Źródło:

W polu Punkt wejścia usuń tekst domyślny i wpisz AvatarApp.
Zmień nazwę domyślnego pliku Java na src/main/java/gcfv2/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 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:

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.
Na liście funkcji kliknij addonchatapp.
Na stronie Szczegóły usługi skopiuj adres URL funkcji. Adres URL kończy się na run.app.
W polu wyszukiwania Google Cloud wpisz „Google Chat API”, a następnie kliknij Google Chat API i Zarządzaj.

Otwórz Chat API
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 wybierz URL punktu końcowego HTTP.
6. Skopiuj adres e-mail konta usługi. Ten adres e-mail jest potrzebny, gdy autoryzujesz 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.
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.

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

Otwórz Cloud Run
Na liście usług Cloud Run zaznacz pole wyboru obok funkcji receiving. (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 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
W sekcji Wybierz rolę kliknij Cloud Run > Wywołujący usługę Cloud Run.
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ść:

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
Kliknij Nowy czat.
W polu Dodaj co najmniej 1 osobę wpisz nazwę aplikacji Chat.
Wybierz aplikację Chat z wyników. Otworzy się czat.

Uwaga: jeśli nie widzisz 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.
Na nowym czacie z aplikacją wpisz Hello i naciśnij enter.

Wiadomość w aplikacji 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, 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.

W konsoli Google Cloud otwórz stronę Zarządzanie zasobami. Kliknij Menu > Administracja > Zarządzaj zasobami.
Otwórz Menedżera zasobów
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.

Tworzenie aplikacji HTTP Google Chat Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Cele

Wymagania wstępne

Konfigurowanie środowiska

Tworzenie i wdrażanie funkcji Cloud Run

Node.js

Python

Java

Konfigurowanie dodatku

Autoryzowanie Google Chat do wywoływania funkcji

Testowanie aplikacji Google Chat

Rozwiązywanie problemów

Czyszczenie danych

Tworzenie aplikacji HTTP Google Chat