Webhook olarak Google Chat uygulaması oluşturma

Bu sayfada, harici tetikleyiciler kullanarak Chat alanına asenkron mesaj göndermek için webhook'ın nasıl ayarlanacağı açıklanmaktadır. Örneğin, bir sunucu kullanımdan kaldırıldığında Chat'te nöbetçi personeli bilgilendirecek bir izleme uygulaması yapılandırabilirsiniz. Chat uygulamasıyla senkronize mesaj göndermek için Mesaj gönderme başlıklı makaleyi inceleyin.

Bu tür bir mimari tasarımında, iletişim tek yönlü olduğundan kullanıcılar webhook'la veya bağlı harici uygulamayla etkileşim kuramaz. Webhook'lar sohbet değildir. Kullanıcılardan mesaj alamaz veya mesajlara yanıt veremez ya da Chat uygulaması etkileşim etkinliklerini göremez. Mesajlara yanıt vermek için webhook yerine Chat uygulaması oluşturun.

Webhook'lar teknik olarak Chat uygulaması olmasa da (webhook'lar standart HTTP istekleri kullanarak uygulamaları birbirine bağlar) bu sayfada basitleştirme amacıyla webhook'lardan Chat uygulaması olarak bahsedilmektedir. Her webhook yalnızca kaydedildiği Chat alanında çalışır. Gelen webhook'lar doğrudan mesajlarda çalışır ancak yalnızca tüm kullanıcıların Chat uygulamalarını etkinleştirdiği durumlarda çalışır. Google Workspace Marketplace'te webhook yayınlayamazsınız.

Aşağıdaki şemada, Chat'e bağlı bir webhook'ın mimarisi gösterilmektedir:

Chat'e eşzamansız mesaj göndermek için gelen webhook'ların mimarisi.

Önceki şemada, Chat uygulamasında aşağıdaki bilgi akışı gösterilmektedir:

  1. Chat uygulama mantığı, proje yönetimi sistemi veya destek kaydı aracı gibi harici üçüncü taraf hizmetlerinden bilgi alır.
  2. Chat uygulaması mantığı, belirli bir Chat alanına webhook URL'si kullanarak mesaj gönderebilen bir bulut veya şirket içi sistemde barındırılır.
  3. Kullanıcılar, söz konusu Chat alanındaki Chat uygulamasından mesaj alabilir ancak Chat uygulamasıyla etkileşimde bulunamaz.

Ön koşullar

Python

  • Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı Google Workspace kuruluşunuz, kullanıcıların gelen webhook'lar eklemesine ve kullanmasına izin vermelidir.
  • Python 3.6 veya sonraki sürümler
  • pip paket yönetim aracı

  • httplib2 kitaplığı. Kitaplığı yüklemek için komut satırı arayüzünüzde aşağıdaki komutu çalıştırın:

    pip install httplib2

  • Google Chat alanı. Google Chat API'yi kullanarak alan oluşturmak için Alan oluşturma başlıklı makaleyi inceleyin. Chat'te grup oluşturmak için Yardım Merkezi belgelerini inceleyin.

Node.js

Java

Apps Komut Dosyası

Web kancası oluşturma

Webhook oluşturmak için webhook'u, mesaj almak istediğiniz Chat alanına kaydedin ve ardından mesaj gönderen bir komut dosyası yazın.

Gelen webhook'ı kaydetme

  1. Bir tarayıcıda Chat'i açın. Webhook'lar Chat mobil uygulamasından yapılandırılamaz.
  2. Webhook eklemek istediğiniz alana gidin.
  3. Alan başlığının yanındaki daha fazla genişletme okunu, ardından Uygulamalar ve entegrasyonları'nı tıklayın.

  4. Webhook ekle'yi tıklayın.

  5. Ad alanına Quickstart Webhook girin.

  6. Avatar URL'si alanına https://developers.google.com/chat/images/chat-product-icon.png girin.

  7. Kaydet'i tıklayın.

  8. Web kancası URL'sini kopyalamak için Diğer'i ve ardından Bağlantıyı kopyala'yı tıklayın.

Webhook komut dosyasını yazma

Örnek webhook komut dosyası, webhook URL'sine bir POST isteği göndererek webhook'ın kayıtlı olduğu alana bir mesaj gönderir. Chat API, Message örneğiyle yanıt verir.

Webhook komut dosyası oluşturmayı öğrenmek için bir dil seçin:

Python

  1. Çalışma dizininizde quickstart.py adlı bir dosya oluşturun.

  2. quickstart.py alanına aşağıdaki kodu yapıştırın:

    python/webhook/quickstart.py
    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. url değişkeninin değerini, web kancasını kaydettiğinizde kopyaladığınız web kancası URL'siyle değiştirin.

Node.js

  1. Çalışma dizininizde index.js adlı bir dosya oluşturun.

  2. index.js alanına aşağıdaki kodu yapıştırın:

    node/webhook/index.js
    /**
 * 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. url değişkeninin değerini, web kancasını kaydettiğinizde kopyaladığınız web kancası URL'siyle değiştirin.

Java

  1. Çalışma dizininizde pom.xml adlı bir dosya oluşturun.

  2. pom.xml alanına aşağıdakileri kopyalayıp yapıştırın:

    java/webhook/pom.xml
    <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. Çalışma dizininizde aşağıdaki dizin yapısını oluşturun src/main/java.

  4. src/main/java dizininde App.java adlı bir dosya oluşturun.

  5. App.java alanına aşağıdaki kodu yapıştırın:

    java/webhook/src/main/java/com/google/chat/webhook/App.java
    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. URL değişkeninin değerini, webhook'u kaydettiğinizde kopyaladığınız webhook URL'siyle değiştirin.

Apps Komut Dosyası

  1. Tarayıcıda Apps Komut Dosyası'na gidin.

  2. Yeni Proje'yi tıklayın.

  3. Aşağıdaki kodu yapıştırın:

    apps-script/webhook/webhook.gs
    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. url değişkeninin değerini, webhook'u kaydettiğinizde kopyaladığınız webhook URL'siyle değiştirin.

Webhook komut dosyasını çalıştırma

Komut satırında komut dosyasını çalıştırın:

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Komut Dosyası

  • Çalıştır'ı tıklayın.

Kodu çalıştırdığınızda webhook, kaydettiğiniz alana bir mesaj gönderir.

Mesaj dizisi başlatma veya mesaj dizisini yanıtlama

  1. Mesaj isteği gövdesinin bir parçası olarak spaces.messages.thread.threadKey değerini belirtin. Bir ileti dizisini başlatıyor veya yanıtlıyor olmanız fark etmeksizin threadKey için aşağıdaki değerleri kullanın:

    • Mesaj dizisi başlatıyorsanız threadKey değerini istediğiniz bir dizeye ayarlayın ancak mesaj dizisine yanıt göndermek için bu değeri not edin.

    • Bir mesaj dizisini yanıtlıyorsanız mesaj dizisi başlatılırken ayarlanan threadKey değerini belirtin. Örneğin, ilk mesajda MY-THREAD kullanıldığı bir mesaj dizisine yanıt göndermek için MY-THREAD değerini ayarlayın.

  2. Belirtilen threadKey bulunamazsa ileti dizisi davranışını tanımlayın:

    • Bir mesaj dizisini yanıtlayın veya yeni bir mesaj dizisi başlatın. messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD parametresini webhook URL'sine ekleyin. Bu URL parametresinin iletilmesi, Chat'in belirtilen threadKey değerini kullanarak mevcut bir ileti dizisini aramasına neden olur. İleti dizisi bulunursa ileti, söz konusu ileti dizisine yanıt olarak yayınlanır. Hiçbiri bulunamazsa mesaj, threadKey'ye karşılık gelen yeni bir mesaj dizisi başlatır.

    • İleti dizisini yanıtlayın veya hiçbir şey yapmayın. messageReplyOption=REPLY_MESSAGE_OR_FAIL parametresini webhook URL'sine ekleyin. Bu URL parametresinin iletilmesi, Chat'in belirtilen threadKey değerini kullanarak mevcut bir ileti dizisini aramasına neden olur. İleti dizisi bulunursa ileti, söz konusu ileti dizisine yanıt olarak yayınlanır. Hiçbiri bulunamazsa mesaj gönderilmez.

    Daha fazla bilgi için messageReplyOption sayfasına bakın.

Aşağıdaki kod örneği, bir mesaj dizisini başlatır veya yanıtlar:

Python

python/webhook/thread-reply.py
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
/**
 * 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));

Apps Komut Dosyası

apps-script/webhook/thread-reply.gs
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);
}

Hataları işleme

Webhook istekleri aşağıdakiler dahil olmak üzere çeşitli nedenlerle başarısız olabilir:

  • Geçersiz istek.
  • Webhook veya webhook'u barındıran alan silinir.
  • Ağ bağlantısı veya kota sınırları gibi aralıklı sorunlar

Webhook'ınızı oluştururken aşağıdakileri yaparak hataları uygun şekilde ele almalısınız:

Google Chat API, hataları google.rpc.Status olarak döndürür. Bu değer, karşılaşılan hatanın türünü belirten bir HTTP hatası code içerir: istemci hatası (400 serisi) veya sunucu hatası (500 serisi). Tüm HTTP eşlemelerini incelemek için google.rpc.Code bölümüne bakın.

{
    "code": 503,
    "message": "The service is currently unavailable.",
    "status": "UNAVAILABLE"
}

HTTP durum kodlarını nasıl yorumlayacağınızı ve hataları nasıl ele alacağınızı öğrenmek için Hatalar başlıklı makaleyi inceleyin.

Sınırlamalar ve dikkat edilmesi gereken hususlar

  • Google Chat API'de bir webhook ile mesaj oluştururken yanıt, mesajın tamamını içermiyor. Yanıt yalnızca name ve thread.name alanlarını doldurur.
  • Webhook'lar, alandaki tüm Chat uygulamaları arasında paylaşılan 60 saniyede 60 spaces.messages.create alan sorgu sınırına tabidir. Chat API kotaları hakkında daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.