یک برنامه Google Chat به عنوان یک وب هوک بسازید

این صفحه نحوه تنظیم یک وب‌هوک برای ارسال پیام‌های غیرهمزمان به فضای چت با استفاده از تریگرهای خارجی را شرح می‌دهد. به عنوان مثال، می‌توانید یک برنامه نظارتی را طوری پیکربندی کنید که هنگام از کار افتادن سرور، به پرسنل حاضر در چت اطلاع دهد. برای ارسال پیام همزمان با یک برنامه چت، به بخش ارسال پیام مراجعه کنید.

با این نوع طراحی معماری، کاربران نمی‌توانند با وب‌هوک یا برنامه خارجی متصل تعامل داشته باشند زیرا ارتباط یک طرفه است. وب‌هوک‌ها محاوره‌ای نیستند. آن‌ها نمی‌توانند به پیام‌های کاربران یا رویدادهای تعاملی برنامه چت پاسخ دهند یا از آن‌ها پیام دریافت کنند. برای پاسخ به پیام‌ها، به جای وب‌هوک، یک برنامه چت بسازید .

اگرچه یک وب‌هوک از نظر فنی یک برنامه چت نیست - وب‌هوک‌ها برنامه‌ها را با استفاده از درخواست‌های استاندارد HTTP به هم متصل می‌کنند - این صفحه برای ساده‌سازی به آن به عنوان یک برنامه چت اشاره می‌کند. هر وب‌هوک فقط در فضای چتی که در آن ثبت شده است کار می‌کند. وب‌هوک‌های ورودی در پیام‌های مستقیم کار می‌کنند، اما فقط زمانی که همه کاربران برنامه‌های چت را فعال کرده باشند. شما نمی‌توانید وب‌هوک‌ها را در بازار فضای کاری گوگل منتشر کنید.

نمودار زیر معماری یک وب‌هوک متصل به چت را نشان می‌دهد:

معماری برای وب‌هوک‌های ورودی جهت ارسال پیام‌های ناهمزمان به چت.

در نمودار قبلی، یک برنامه چت جریان اطلاعات زیر را دارد:

  1. منطق برنامه چت، اطلاعات را از سرویس‌های شخص ثالث خارجی، مانند یک سیستم مدیریت پروژه یا یک ابزار تیکتینگ، دریافت می‌کند.
  2. منطق برنامه چت در یک سیستم ابری یا داخلی میزبانی می‌شود که می‌تواند با استفاده از یک URL وب‌هوک به یک فضای چت خاص پیام ارسال کند.
  3. کاربران می‌توانند در آن فضای چت خاص، پیام‌هایی از برنامه چت دریافت کنند، اما قادر به تعامل با برنامه چت نیستند.

پیش‌نیازها

پایتون

نود جی اس

جاوا

اسکریپت برنامه‌ها

ایجاد یک وب هوک

برای ایجاد یک وب‌هوک، آن را در فضای چتی که می‌خواهید پیام‌ها را دریافت کنید، ثبت کنید و سپس اسکریپتی بنویسید که پیام‌ها را ارسال کند.

وب هوک ورودی را ثبت کنید

  1. در مرورگر، چت را باز کنید. وب‌هوک‌ها از طریق برنامه موبایل چت قابل تنظیم نیستند.
  2. به فضایی که می‌خواهید یک وب‌هوک اضافه کنید، بروید.
  3. در کنار عنوان فضا، روی فلش expand more کلیک کنید و سپس روی Apps & integrations کلیک کنید.

  4. وب‌هوک‌ها کلیک کنید.

  5. در فیلد نام ، Quickstart Webhook وارد کنید.

  6. در فیلد آدرس اینترنتی آواتار ، https://developers.google.com/chat/images/chat-product-icon.png را وارد کنید.

  7. روی ذخیره کلیک کنید.

  8. برای کپی کردن آدرس وب‌هوک، روی More کلیک کنید و سپس روی Copy link کلیک کنید.

اسکریپت وب هوک را بنویسید

اسکریپت وب‌هوک نمونه با ارسال یک درخواست POST به آدرس وب‌هوک، پیامی را به فضایی که وب‌هوک در آن ثبت شده است، ارسال می‌کند. API چت با نمونه‌ای از Message پاسخ می‌دهد.

برای یادگیری نحوه ایجاد اسکریپت وب هوک، یک زبان را انتخاب کنید:

پایتون

  1. در دایرکتوری کاری خود، فایلی با نام quickstart.py ایجاد کنید.

  2. در quickstart.py ، کد زیر را قرار دهید:

    پایتون/وب‌هوک/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 را با آدرس وب‌هوک که هنگام ثبت وب‌هوک کپی کرده‌اید، جایگزین کنید.

نود جی اس

  1. در دایرکتوری کاری خود، فایلی با نام index.js ایجاد کنید.

  2. در index.js ، کد زیر را قرار دهید:

    گره/وب‌هوک/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 را با آدرس وب‌هوک که هنگام ثبت وب‌هوک کپی کرده‌اید، جایگزین کنید.

جاوا

  1. در دایرکتوری کاری خود، فایلی با نام pom.xml ایجاد کنید.

  2. در pom.xml ، کد زیر را کپی و پیست کنید:

    جاوا/وب‌هوک/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. در دایرکتوری کاری خود، ساختار دایرکتوری زیر را ایجاد کنید src/main/java .

  4. در پوشه src/main/java ، فایلی با نام App.java ایجاد کنید.

  5. در App.java ، کد زیر را قرار دهید:

    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 را با URL وب‌هوک که هنگام ثبت وب‌هوک کپی کرده‌اید، جایگزین کنید.

اسکریپت برنامه‌ها

  1. در مرورگر، به Apps Script بروید.

  2. روی پروژه جدید کلیک کنید

  3. کد زیر را جایگذاری کنید:

    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 را با آدرس وب‌هوک که هنگام ثبت وب‌هوک کپی کرده‌اید، جایگزین کنید.

اسکریپت وب هوک را اجرا کنید

در یک رابط خط فرمان (CLI)، اسکریپت را اجرا کنید:

پایتون 

  python3 quickstart.py

نود جی اس 

  node index.js

جاوا 

  mvn compile exec:java -Dexec.mainClass=App

اسکریپت برنامه‌ها

  • روی اجرا کلیک کنید.

وقتی کد را اجرا می‌کنید، وب‌هوک پیامی را به فضایی که در آن ثبت نام کرده‌اید ارسال می‌کند.

شروع یا پاسخ به یک رشته پیام

  1. spaces.messages.thread.threadKey به عنوان بخشی از بدنه درخواست پیام مشخص کنید. بسته به اینکه آیا یک نخ را شروع می‌کنید یا به آن پاسخ می‌دهید، از مقادیر زیر برای threadKey استفاده کنید:

    • اگر می‌خواهید یک تاپیک شروع کنید، threadKey روی یک رشته دلخواه تنظیم کنید، اما برای ارسال پاسخ به تاپیک، این مقدار را یادداشت کنید.

    • اگر به یک رشته پاسخ می‌دهید، threadKey که هنگام شروع رشته تنظیم شده است، مشخص کنید. برای مثال، برای ارسال پاسخ به رشته‌ای که پیام اولیه از MY-THREAD استفاده کرده است، MY-THREAD تنظیم کنید.

  2. اگر threadKey مشخص شده پیدا نشد، رفتار thread را تعریف کنید:

    • به یک رشته پاسخ دهید یا یک رشته جدید شروع کنید. پارامتر messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD را به آدرس اینترنتی webhook اضافه کنید. ارسال این پارامتر URL باعث می‌شود Chat با استفاده از threadKey مشخص شده، به دنبال یک رشته موجود بگردد. اگر رشته‌ای پیدا شود، پیام به عنوان پاسخی به آن رشته ارسال می‌شود. اگر رشته‌ای پیدا نشود، پیام یک رشته جدید مطابق با آن threadKey شروع می‌کند.

    • به یک رشته پاسخ دهید یا هیچ کاری نکنید. پارامتر messageReplyOption=REPLY_MESSAGE_OR_FAIL را به آدرس اینترنتی webhook اضافه کنید. ارسال این پارامتر URL باعث می‌شود Chat با استفاده از threadKey مشخص شده، به دنبال یک رشته موجود بگردد. اگر رشته‌ای پیدا شود، پیام به عنوان پاسخی به آن رشته ارسال می‌شود. اگر رشته‌ای پیدا نشود، پیام ارسال نمی‌شود.

    برای کسب اطلاعات بیشتر، به messageReplyOption مراجعه کنید.

نمونه کد زیر یک رشته پیام را شروع می‌کند یا به آن پاسخ می‌دهد:

پایتون

پایتون/وب‌هوک/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()

نود جی اس

گره/وب‌هوک/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-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);
}

مدیریت خطاها

درخواست‌های وب‌هوک می‌توانند به دلایل مختلفی از جمله موارد زیر با شکست مواجه شوند:

  • درخواست نامعتبر.
  • وب‌هوک یا فضایی که وب‌هوک در آن قرار دارد حذف شده است.
  • مشکلات متناوب مانند اتصال به شبکه یا محدودیت‌های سهمیه‌بندی.

هنگام ساخت وب‌هوک خود، باید به طور مناسب خطاها را با موارد زیر مدیریت کنید:

API چت گوگل، خطاها را به صورت google.rpc.Status برمی‌گرداند که شامل یک code خطای HTTP است که نوع خطای رخ داده را نشان می‌دهد: خطای کلاینت (سری ۴۰۰) یا خطای سرور (سری ۵۰۰). برای بررسی تمام نگاشت‌های HTTP، به google.rpc.Code مراجعه کنید. 

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

برای یادگیری نحوه تفسیر کدهای وضعیت HTTP و مدیریت خطاها، به بخش خطاها مراجعه کنید.

محدودیت‌ها و ملاحظات

  • هنگام ایجاد پیام با استفاده از وب‌هوک در Google Chat API، پاسخ شامل کل پیام نیست. پاسخ فقط فیلدهای name و thread.name پر می‌کند.
  • وب‌هوک‌ها تابع سهمیه هر فضا برای spaces.messages.create هستند: ۱ درخواست در ثانیه، که بین همه وب‌هوک‌های موجود در فضا به اشتراک گذاشته می‌شود. چت همچنین ممکن است درخواست‌های وب‌هوک را که بیش از ۱ پرس‌وجو در ثانیه در همان فضا دارند، رد کند. برای اطلاعات بیشتر در مورد سهمیه‌های API چت، به محدودیت‌های استفاده مراجعه کنید.