Tworzenie aplikacji Google Chat jako webhooka

Na tej stronie opisujemy, jak skonfigurować webhooka do wysyłania wiadomości asynchronicznych do pokoju czatu przy użyciu zewnętrznych aktywatorów. Możesz na przykład skonfigurować aplikację do monitorowania w Google Chat, która będzie powiadamiała personel dyżurny o awariach serwera. Informacje o wysyłaniu wiadomości synchronicznej za pomocą aplikacji Google Chat znajdziesz w sekcji Wysyłanie wiadomości.

Przy tego typu architekturze użytkownicy nie mogą korzystać z webhooka ani połączonej aplikacji zewnętrznej, ponieważ komunikacja jest jednokierunkowa. Webhooki nie służą do rozmów. Nie mogą odpowiadać na wiadomości użytkowników ani ich odpowiadać na zdarzenia interakcji z aplikacją Google Chat ani ich otrzymywać. Aby odpowiadać na wiadomości, utwórz aplikację Google Chat zamiast webhooka.

Webhook nie jest w zasadzie aplikacją do obsługi czatu – webhooki łączą aplikacje za pomocą standardowych żądań HTTP. Dla uproszczenia na tej stronie jest to aplikacja do obsługi czatu. Każdy webhook działa tylko w pokoju czatu, w którym jest zarejestrowany. Przychodzące webhooki działają na czacie, ale tylko wtedy, gdy wszyscy użytkownicy mają włączone aplikacje Google Chat. Nie będzie można publikować webhooków w Google Workspace Marketplace.

Poniższy diagram przedstawia architekturę webhooka połączonego z Google Chat:

Na poprzednim diagramie aplikacja do obsługi czatu zawiera następujący przepływ informacji:

1. Logika aplikacji Google Chat otrzymuje informacje z usług zewnętrznych, takich jak system zarządzania projektami czy narzędzie do zgłaszania zgłoszeń.
2. Logika aplikacji Google Chat jest hostowana w chmurze lub w systemie lokalnym, który może wysyłać wiadomości przy użyciu adresu URL webhooka do określonego pokoju czatu.
3. Użytkownicy mogą odbierać wiadomości z aplikacji Google Chat w tym konkretnym pokoju, ale nie mogą korzystać z aplikacji Google Chat.

Wymagania wstępne

Python

• Python 3.10.7 lub nowszy.
• Konto Google Workspace z dostępem do Google Chat.
• Dotychczasowy pokój czatu.

• Biblioteka httplib2. W razie potrzeby uruchom to polecenie interfejsu wiersza poleceń, aby zainstalować bibliotekę za pomocą pip:

  pip install httplib2
  

Node.js

• Zainstalowano Node.js i npm.
• Konto Google Workspace z dostępem do Google Chat.
• Dotychczasowy pokój czatu.

Java

• Java 11 lub nowsza.
• Apache Maven
• Konto Google Workspace z dostępem do Google Chat.
• Dotychczasowy pokój czatu.

Google Apps Script

• konto Google Workspace z dostępem do Google Chat.
• Dotychczasowy pokój czatu.

Tworzenie webhooka

Aby utworzyć webhooka, zarejestruj go w pokoju czatu, w którym chcesz otrzymywać wiadomości, a potem napisz skrypt, który będzie je wysyłać.

Zarejestruj przychodzącego webhooka

1. Otwórz Google Chat w przeglądarce. W aplikacji mobilnej Google Chat nie można konfigurować webhooków.
2. Otwórz pokój, w którym chcesz dodać webhooka.
3. Obok nazwy pokoju kliknij strzałkę rozwijania , a następnie kliknij Aplikacje i integracje.
4. Kliknij Dodaj webhooki.
5. W polu Nazwa wpisz Quickstart Webhook.
6. W polu Awatar URL wpisz https://developers.google.com/chat/images/chat-product-icon.png.
7. Kliknij Zapisz.
8. Aby skopiować adres URL webhooka, kliknij Więcej, a następnie Kopiuj link.

Pisanie skryptu webhooka

Przykładowy skrypt webhooka wysyła wiadomość do pokoju, w którym został zarejestrowany webhook, wysyłając żądanie POST na adres URL webhooka. Interfejs Chat API odpowiada z instancji Message.

Wybierz język, aby dowiedzieć się, jak utworzyć skrypt webhooka:

Python

1. W katalogu roboczym utwórz plik o nazwie quickstart.py.

2. W interfejsie quickstart.py wklej ten kod:

   python/webhook/quickstart.py

   Wyświetl w GitHubie

   from json import dumps
   from httplib2 import Http
   
   # Copy the webhook URL from the Chat space where the webhook is registered.
   # The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
   # when you copy the webhook URL.
   
   def main():
       """Google Chat incoming webhook quickstart."""
       url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN"
       app_message = {"text": "Hello from a Python script!"}
       message_headers = {"Content-Type": "application/json; charset=UTF-8"}
       http_obj = Http()
       response = http_obj.request(
           uri=url,
           method="POST",
           headers=message_headers,
           body=dumps(app_message),
       )
       print(response)
   
   
   if __name__ == "__main__":
       main()

3. Zastąp wartość zmiennej url adresem URL webhooka skopiowanym podczas jego rejestracji.

Node.js

1. W katalogu roboczym utwórz plik o nazwie index.js.

2. W interfejsie index.js wklej ten kod:

   node/webhook/index.js

   Wyświetl w GitHubie

   /**
    * Sends asynchronous message to Google Chat
    * @return {Object} response
    */
   async function webhook() {
     const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
     const res = await fetch(url, {
       method: "POST",
       headers: {"Content-Type": "application/json; charset=UTF-8"},
       body: JSON.stringify({text: "Hello from a Node script!"})
     });
     return await res.json();
   }
   
   webhook().then(res => console.log(res));

3. Zastąp wartość zmiennej url adresem URL webhooka skopiowanym podczas jego rejestracji.

Java

1. W katalogu roboczym utwórz plik o nazwie pom.xml.

2. W aplikacji pom.xml skopiuj i wklej ten kod:

   java/webhook/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>com.google.chat.webhook</groupId>
     <artifactId>java-webhook-app</artifactId>
     <version>0.1.0</version>
   
     <name>java-webhook-app</name>
     <url>https://github.com/googleworkspace/google-chat-samples/tree/main/java/webhook</url>
   
     <properties>
       <maven.compiler.target>11</maven.compiler.target>
       <maven.compiler.source>11</maven.compiler.source>
     </properties>
   
     <dependencies>
       <dependency>
           <groupId>com.google.code.gson</groupId>
           <artifactId>gson</artifactId>
           <version>2.9.1</version>
       </dependency>
     </dependencies>
   
     <build>
       <pluginManagement>
         <plugins>
           <plugin>
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.8.0</version>
           </plugin>
         </plugins>
       </pluginManagement>
     </build>
   </project>

3. W katalogu roboczym utwórz taką strukturę katalogów: src/main/java.

4. W katalogu src/main/java utwórz plik o nazwie App.java.

5. W interfejsie App.java wklej ten kod:

   java/webhook/src/main/java/com/google/chat/webhook/App.java

   Wyświetl w GitHubie

   import com.google.gson.Gson;
   import java.net.http.HttpClient;
   import java.net.http.HttpRequest;
   import java.net.http.HttpResponse;
   import java.util.Map;
   import java.net.URI;
   
   public class App {
     private static final String URL = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages";
     private static final Gson gson = new Gson();
     private static final HttpClient client = HttpClient.newHttpClient();
   
     public static void main(String[] args) throws Exception {
       String message = gson.toJson(Map.of("text", "Hello from Java!"));
   
       HttpRequest request = HttpRequest.newBuilder(
           URI.create(URL))
           .header("accept", "application/json; charset=UTF-8")
           .POST(HttpRequest.BodyPublishers.ofString(message))
           .build();
   
       HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
   
       System.out.println(response.body());
     }
   }

6. Zastąp wartość zmiennej URL adresem URL webhooka skopiowanym podczas jego rejestracji.

Google Apps Script

1. W przeglądarce otwórz Apps Script.

2. Kliknij Nowy projekt.

3. Wklej ten kod:

   apps-script/webhook/webhook.gs

   Wyświetl w GitHubie

   function webhook() {
     const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
     const options = {
       "method": "post",
       "headers": {"Content-Type": "application/json; charset=UTF-8"},
       "payload": JSON.stringify({"text": "Hello from Apps Script!"})
     };
     const response = UrlFetchApp.fetch(url, options);
     console.log(response);
   }

4. Zastąp wartość zmiennej url adresem URL webhooka skopiowanym podczas jego rejestracji.

Uruchom skrypt webhooka

W interfejsie wiersza poleceń uruchom skrypt:

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

Google Apps Script

• Kliknij Uruchom.

Gdy uruchomisz kod, webhook wyśle wiadomość do pokoju, w którym go zarejestrowano.

Rozpoczynanie wątku wiadomości lub odpowiadanie w nim

1. W treści żądania wiadomości podaj spaces.messages.thread.threadKey. W zależności od tego, czy rozpoczynasz wątek, czy na niego odpowiadasz, użyj dla threadKey tych wartości:

   • Jeśli rozpoczynasz wątek, ustaw threadKey na dowolny ciąg znaków, ale zanotuj tę wartość, aby opublikować odpowiedź w wątku.

   • Jeśli odpowiadasz na wątek, podaj właściwość threadKey, która została ustawiona podczas rozpoczęcia wątku. Aby na przykład opublikować odpowiedź w wątku, w którym w początkowej wiadomości był używany znak MY-THREAD, ustaw atrybut MY-THREAD.

2. Określ działanie wątku, jeśli nie zostanie znaleziony parametr threadKey:

   • Odpowiedz w wątku lub rozpocznij nowy. Dodaj parametr messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD do adresu URL webhooka. Przekazanie tego parametru adresu URL spowoduje, że Google Chat wyszuka istniejący wątek za pomocą podanego atrybutu threadKey. w przypadku znalezienia odpowiedzi, wiadomość jest publikowana jako odpowiedź w tym wątku. Jeśli nie uda się znaleźć żadnej wiadomości, wiadomość rozpocznie nowy wątek odpowiadający temu threadKey.

   • Odpowiadaj w wątku lub nic nie rób. Dodaj parametr messageReplyOption=REPLY_MESSAGE_OR_FAIL do adresu URL webhooka. Przekazanie tego parametru adresu URL spowoduje, że Google Chat wyszuka istniejący wątek za pomocą podanego atrybutu threadKey. w przypadku znalezienia odpowiedzi, wiadomość jest publikowana jako odpowiedź w tym wątku. Jeśli nie uda się znaleźć żadnej wiadomości, wiadomość nie zostanie wysłana.

   Więcej informacji: messageReplyOption.

Ten przykładowy kod uruchamia wątek lub odpowiada w wątku wiadomości:

Python

python/webhook/thread-reply.py

Wyświetl w GitHubie

from json import dumps
from httplib2 import Http

# Copy the webhook URL from the Chat space where the webhook is registered.
# The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
# when you copy the webhook URL.
#
# Then, append messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD to the
# webhook URL.


def main():
    """Google Chat incoming webhook that starts or replies to a message thread."""
    url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
    app_message = {
        "text": "Hello from a Python script!",
        # To start a thread, set threadKey to an arbitratry string.
        # To reply to a thread, specify that thread's threadKey value.
        "thread": {"threadKey": "THREAD_KEY_VALUE"},
    }
    message_headers = {"Content-Type": "application/json; charset=UTF-8"}
    http_obj = Http()
    response = http_obj.request(
        uri=url,
        method="POST",
        headers=message_headers,
        body=dumps(app_message),
    )
    print(response)


if __name__ == "__main__":
    main()

Node.js

node/webhook/thread-reply.js

Wyświetl w GitHubie

/**
 * Sends asynchronous message to Google Chat
 * @return {Object} response
 */
async function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const res = await fetch(url, {
    method: "POST",
    headers: {"Content-Type": "application/json; charset=UTF-8"},
    body: JSON.stringify({
      text: "Hello from a Node script!",
      thread: {threadKey: "THREAD_KEY_VALUE"}
    })
  });
  return await res.json();
}

webhook().then(res => console.log(res));

Google Apps Script

apps-script/webhook/thread-reply.gs

Wyświetl w GitHubie

function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const options = {
    "method": "post",
    "headers": {"Content-Type": "application/json; charset=UTF-8"},
    "payload": JSON.stringify({
      "text": "Hello from Apps Script!",
      "thread": {"threadKey": "THREAD_KEY_VALUE"}
    })
  };
  const response = UrlFetchApp.fetch(url, options);
  console.log(response);
}

Powiązane artykuły

• Wybieranie architektury aplikacji do obsługi Google Chat
• Wysyłanie wiadomości dotyczących karty
• Formatowanie wiadomości