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

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

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

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

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

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

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

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

پیش نیازها

پایتون

Node.js

جاوا

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

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

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

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

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

  4. روی وب هوک کلیک کنید.

  5. در قسمت نام ، Quickstart Webhook وارد کنید.

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

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

  8. برای کپی کردن URL webhook، روی More کلیک کنید و سپس روی Copy link کلیک کنید.

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

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

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

پایتون

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

  2. در quickstart.py کد زیر را جایگذاری کنید:

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

Node.js

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

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

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

جاوا

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

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

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

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

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

  2. روی New Project کلیک کنید

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

اسکریپت webhook را اجرا کنید

در یک CLI، اسکریپت را اجرا کنید:

پایتون 

  python3 quickstart.py

Node.js 

  node index.js

جاوا 

  mvn compile exec:java -Dexec.mainClass=App

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

  • روی Run کلیک کنید.

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

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

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

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

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

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

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

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

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

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

پایتون

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-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);
}

رسیدگی به خطاها

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

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

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

Google Chat API خطاها را به‌عنوان google.rpc.Status برمی‌گرداند که شامل یک code خطای HTTP است که نشان‌دهنده نوع خطایی است که با آن مواجه شده‌اند: خطای سرویس گیرنده (سری 400) یا خطای سرور (سری 500). برای بررسی همه نگاشت‌های HTTP، به google.rpc.Code مراجعه کنید. 

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

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

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

  • هنگام ایجاد یک پیام با یک هوک در Google Chat API، پاسخ حاوی پیام کامل نیست. پاسخ فقط فیلدهای name و thread.name را پر می کند.