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

این صفحه نحوه ساخت افزونه‌ای برای Google Workspace را توضیح می‌دهد که با استفاده از سرویس HTTP در Google Chat کار می‌کند.

این آموزش سریع به شما نشان می‌دهد که چگونه یک سرویس HTTP با استفاده از سرویس‌های Google Cloud بسازید. برای ساخت برنامه چت، شما یک تابع Cloud Run می‌نویسید و آن را مستقر می‌کنید که برنامه چت از آن برای پاسخ به پیام کاربر استفاده می‌کند.

با معماری HTTP، شما Chat را طوری پیکربندی می‌کنید که با استفاده از HTTP با Google Cloud یا یک سرور داخلی ادغام شود، همانطور که در نمودار زیر نشان داده شده است:

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

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

  1. کاربر پیامی را در چت به یک برنامه چت، چه در پیام مستقیم و چه در فضای چت، ارسال می‌کند.
  2. یک درخواست HTTP به یک وب سرور ارسال می‌شود که می‌تواند یک سیستم ابری یا داخلی باشد و شامل منطق برنامه چت است.
  3. به صورت اختیاری، منطق برنامه چت می‌تواند با سرویس‌های Google Workspace (مانند Calendar و Sheets)، سایر سرویس‌های گوگل (مانند Maps، YouTube و Vertex AI) یا سایر سرویس‌های وب (مانند سیستم مدیریت پروژه یا ابزار تیکتینگ) ادغام شود.
  4. وب سرور یک پاسخ HTTP را به سرویس برنامه چت در Chat ارسال می‌کند.
  5. پاسخ به کاربر تحویل داده می‌شود.
  6. به صورت اختیاری، برنامه چت می‌تواند API چت را برای ارسال پیام‌ها یا انجام سایر عملیات به صورت غیرهمزمان فراخوانی کند.

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

اهداف

  • محیط خود را تنظیم کنید.
  • یک تابع Cloud Run ایجاد و مستقر کنید.
  • افزونه‌ی Google Workspace را برای برنامه‌ی چت پیکربندی کنید.
  • برنامه را تست کنید.

پیش‌نیازها

محیط را تنظیم کنید

قبل از استفاده از APIهای گوگل، باید آنها را در یک پروژه گوگل کلود فعال کنید. می‌توانید یک یا چند API را در یک پروژه گوگل کلود فعال کنید.
  • در کنسول Google Cloud، APIهای Cloud Build، Cloud Functions API، Cloud Pub/Sub API، Cloud Logging API، Artifact Registry API و Cloud Run API را فعال کنید.

    فعال کردن APIها

یک تابع Cloud Run ایجاد و مستقر کنید

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

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

نود جی اس

  1. در کنسول گوگل کلود، به صفحه Cloud Run بروید:

    به Cloud Run بروید

    مطمئن شوید که پروژه مربوط به برنامه چت شما انتخاب شده است.

  2. روی نوشتن یک تابع کلیک کنید.

  3. در صفحه ایجاد سرویس ، تابع خود را تنظیم کنید:

    1. در فیلد نام سرویس ، addonchatapp را وارد کنید.
    2. در لیست منطقه ، یک منطقه را انتخاب کنید.
    3. در لیست Runtime ، جدیدترین نسخه Node.js را انتخاب کنید.
    4. در بخش احراز هویت ، گزینه «احراز هویت الزامی» را انتخاب کنید.
    5. روی Create کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به تب Source هدایت می‌کند.
  4. در برگه منبع :

    1. در قسمت Entry point ، متن پیش‌فرض را حذف کرده و avatarApp وارد کنید.
    2. محتویات فایل index.js را با کد زیر جایگزین کنید:
    گره/چت/آواتار-برنامه/index.js
    import { http } from '@google-cloud/functions-framework';
    
    // The ID of the slash command "/about".
    // You must use the same ID in the Google Chat API configuration.
    const ABOUT_COMMAND_ID = 1;
    
    /**
     * Handle requests from Google Workspace add on
     *
     * @param {Object} req Request sent by Google Chat
     * @param {Object} res Response to be sent back to Google Chat
     */
    http('avatarApp', (req, res) => {
      const chatEvent = req.body.chat;
      let message;
      if (chatEvent.appCommandPayload) {
        message = handleAppCommand(chatEvent);
      } else {
        message = handleMessage(chatEvent);
      }
      res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
        message: message
      }}}});
    });
    
    /**
     * Responds to an APP_COMMAND event in Google Chat.
     *
     * @param {Object} event the event object from Google Chat
     * @return the response message object.
     */
    function handleAppCommand(event) {
      switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
        case ABOUT_COMMAND_ID:
          return {
            text: 'The Avatar app replies to Google Chat messages.'
          };
      }
    }
    
    /**
     * Responds to a MESSAGE event in Google Chat.
     *
     * @param {Object} event the event object from Google Chat
     * @return the response message object.
     */
    function handleMessage(event) {
      // Stores the Google Chat user as a variable.
      const chatUser = event.messagePayload.message.sender;
      const displayName = chatUser.displayName;
      const avatarUrl = chatUser.avatarUrl;
      return {
        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 }
            }]}]
          }
        }]
      };
    }
    1. روی ذخیره و استقرار مجدد کلیک کنید.

پایتون

  1. در کنسول گوگل کلود، به صفحه Cloud Run بروید:

    به Cloud Run بروید

    مطمئن شوید که پروژه مربوط به برنامه چت شما انتخاب شده است.

  2. روی نوشتن یک تابع کلیک کنید.

  3. در صفحه ایجاد سرویس ، تابع خود را تنظیم کنید:

    1. در فیلد نام سرویس ، addonchatapp را وارد کنید.
    2. در لیست منطقه ، یک منطقه را انتخاب کنید.
    3. در لیست Runtime ، جدیدترین نسخه پایتون را انتخاب کنید.
    4. در بخش احراز هویت ، گزینه «احراز هویت الزامی» را انتخاب کنید.
    5. روی Create کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به تب Source هدایت می‌کند.
  4. در برگه منبع :

    1. در قسمت Entry point ، متن پیش‌فرض را حذف کرده و avatar_app وارد کنید.
    2. محتویات main.py را با کد زیر جایگزین کنید:
    پایتون/چت/آواتار-اپ/اصلی.پایتون
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # The ID of the slash command "/about".
    # You must use the same ID in the Google Chat API configuration.
    ABOUT_COMMAND_ID = 1
    
    @functions_framework.http
    def avatar_app(req: flask.Request) -> Mapping[str, Any]:
      """Handle requests from Google Workspace add on
    
      Args:
        flask.Request req: the request sent by Google Chat
    
      Returns:
        Mapping[str, Any]: the response to be sent back to Google Chat
      """
      chat_event = req.get_json(silent=True)["chat"]
      if chat_event and "appCommandPayload" in chat_event:
        message = handle_app_command(chat_event)
      else:
        message = handle_message(chat_event)
      return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
          "message": message
      }}}}
    
    def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
      """Responds to an APP_COMMAND event in Google Chat.
    
      Args:
        Mapping[str, Any] event: the event object from Google Chat
    
      Returns:
        Mapping[str, Any]: the response message object.
      """
      if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
        return {
          "text": "The Avatar app replies to Google Chat messages.",
        }
      return {}
    
    def handle_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
      """Responds to a MESSAGE event in Google Chat.
    
      Args:
        Mapping[str, Any] event: the event object from Google Chat
    
      Returns:
        Mapping[str, Any]: the response message object.
      """
      # Stores the Google Chat user as a variable.
      chat_user = event["messagePayload"]["message"]["sender"]
      display_name = chat_user.get("displayName", "")
      avatar_url = chat_user.get("avatarUrl", "")
      return {
        "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 }},
            ]}]
          }
        }]
      }
    1. روی ذخیره و استقرار مجدد کلیک کنید.

جاوا

  1. در کنسول گوگل کلود، به صفحه Cloud Run بروید:

    به Cloud Run بروید

    مطمئن شوید که پروژه مربوط به برنامه چت شما انتخاب شده است.

  2. روی نوشتن یک تابع کلیک کنید.

  3. در صفحه ایجاد سرویس ، تابع خود را تنظیم کنید:

    1. در فیلد نام سرویس ، addonchatapp را وارد کنید.
    2. در لیست منطقه ، یک منطقه را انتخاب کنید.
    3. در لیست Runtime ، جدیدترین نسخه جاوا را انتخاب کنید.
    4. در بخش احراز هویت ، گزینه «احراز هویت الزامی» را انتخاب کنید.
    5. روی Create کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به تب Source هدایت می‌کند.
  4. در برگه منبع :

    1. در قسمت Entry point ، متن پیش‌فرض را حذف کرده و App وارد کنید.
    2. فایل پیش‌فرض جاوا را به src/main/java/com/google/chat/avatar/App.java تغییر نام دهید.
    3. محتویات App.java را با کد زیر جایگزین کنید:
    java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java
    package com.google.chat.avatar;
    
    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;
    import java.util.List;
    
    public class App implements HttpFunction {
      // The ID of the slash command "/about".
      // You must use the same ID in the Google Chat API configuration.
      private static final int ABOUT_COMMAND_ID = 1;
    
      private static final Gson gson = new Gson();
    
      /**
       * Handle requests from Google Workspace add on
       * 
       * @param request the request sent by Google Chat
       * @param response the response to be sent back to Google Chat
       */
      @Override
      public void service(HttpRequest request, HttpResponse response) throws Exception {
        JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
        JsonObject chatEvent = event.getAsJsonObject("chat");
        Message message;
        if (chatEvent.has("appCommandPayload")) {
          message = handleAppCommand(chatEvent);
        } else {
          message = handleMessage(chatEvent);
        }
        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));
      }
    
      /**
       * Handles an APP_COMMAND event in Google Chat.
       *
       * @param event the event object from Google Chat
       * @return the response message object.
       */
      private Message handleAppCommand(JsonObject event) throws Exception {
        switch (event.getAsJsonObject("appCommandPayload")
          .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
          case ABOUT_COMMAND_ID:
            return new Message()
              .setText("The Avatar app replies to Google Chat messages.");
          default:
            return null;
        }
      }
    
      /**
       * Handles a MESSAGE event in Google Chat.
       *
       * @param event the event object from Google Chat
       * @return the response message object.
       */
      private Message handleMessage(JsonObject event) throws Exception {
        // Stores the Google Chat user as a variable.
        JsonObject chatUser = event.getAsJsonObject("messagePayload").getAsJsonObject("message").getAsJsonObject("sender");
        String displayName = chatUser.has("displayName") ? chatUser.get("displayName").getAsString() : "";
        String avatarUrl = chatUser.has("avatarUrl") ? chatUser.get("avatarUrl").getAsString() : "";
        return new Message()
          .setText("Here's your avatar")
          .setCardsV2(List.of(new CardWithId()
            .setCardId("avatarCard")
            .setCard(new GoogleAppsCardV1Card()
              .setName("Avatar Card")
              .setHeader(new GoogleAppsCardV1CardHeader()
                .setTitle(String.format("Hello %s!", displayName)))
              .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
                new GoogleAppsCardV1Widget().setTextParagraph(new GoogleAppsCardV1TextParagraph()
                  .setText("Your avatar picture:")),
                new GoogleAppsCardV1Widget()
                  .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
      }
    }
  5. محتویات pom.xml را با کد زیر جایگزین کنید:

    java/chat/avatar-app/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</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.1.4</version>
        </dependency>
        <dependency>
          <groupId>com.google.code.gson</groupId>
          <artifactId>gson</artifactId>
          <version>2.9.1</version>
        </dependency>
        <dependency>
          <groupId>com.google.apis</groupId>
          <artifactId>google-api-services-chat</artifactId>
          <version>v1-rev20230115-2.0.0</version>
        </dependency>
      </dependencies>
    
      <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>
    1. روی ذخیره و استقرار مجدد کلیک کنید.

صفحه جزئیات سرویس Cloud Run باز می‌شود. منتظر بمانید تا عملکرد اجرا شود.

افزونه را پیکربندی کنید

پس از استقرار عملکرد Cloud Run، این مراحل را برای ایجاد یک افزونه و استقرار برنامه Google Chat دنبال کنید:

  1. در کنسول گوگل کلود، به صفحه Cloud Run بروید:

    به Cloud Run بروید

    مطمئن شوید پروژه‌ای که Cloud Run را برای آن فعال کرده‌اید، انتخاب شده است.

  2. در لیست توابع، روی addonchatapp کلیک کنید.

  3. در صفحه جزئیات سرویس ، آدرس اینترنتی (URL) تابع را کپی کنید. آدرس اینترنتی به run.app ختم می‌شود.

  4. در فیلد جستجوی Google Cloud، عبارت «Google Chat API» را جستجو کنید، سپس روی Google Chat API کلیک کنید و سپس روی مدیریت (Manage) کلیک کنید.

    به API چت بروید

  5. روی پیکربندی کلیک کنید و برنامه Google Chat را تنظیم کنید:

    1. در قسمت نام برنامه ، Add-on Chat app را وارد کنید.
    2. در قسمت آدرس اینترنتی آواتار ، آدرس https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png را وارد کنید.
    3. در قسمت توضیحات ، Add-on Chat app را وارد کنید.
    4. در بخش عملکرد ، گزینه «پیوستن به فضاها و مکالمات گروهی» را انتخاب کنید.
    5. در قسمت تنظیمات اتصال ، آدرس اینترنتی نقطه پایانی HTTP را انتخاب کنید.
    6. ایمیل حساب سرویس را کپی کنید. هنگام تأیید افزونه برای فراخوانی تابع، به این ایمیل نیاز دارید.
    7. در قسمت Triggers ، گزینه Use a common HTTP endpoint URL for all triggers را انتخاب کنید و URL مربوط به تریگر تابع Cloud Run را در کادر مربوطه جایگذاری کنید.
    8. در قسمت «قابلیت مشاهده» ، گزینه «این برنامه چت گوگل را برای افراد و گروه‌های خاص در دامنه خود در دسترس قرار دهید» را انتخاب کنید و آدرس ایمیل خود را وارد کنید.
    9. در قسمت گزارش‌ها ، گزینه ثبت خطاها را برای ثبت گزارش‌ها انتخاب کنید.
  6. روی ذخیره کلیک کنید.

در مرحله بعد، به برنامه چت اجازه دهید تا عملکرد Cloud Run را فراخوانی کند.

به گوگل چت اجازه دهید تا تابع شما را فراخوانی کند

برای مجاز کردن افزونه‌ی Google Workspace برای فراخوانی تابع خود، حساب سرویس افزونه‌ی Google Workspace را با نقش فراخوانی‌کننده‌ی سرویس Cloud Run اضافه کنید.

  1. در کنسول گوگل کلود، به صفحه Cloud Run بروید:

    به Cloud Run بروید

  2. در لیست سرویس‌های Cloud Run، کادر کنار تابع دریافت را علامت بزنید. (روی خود تابع کلیک نکنید.)

  3. روی مجوزها کلیک کنید. پنل مجوزها باز می‌شود.

  4. روی افزودن مدیر اصلی کلیک کنید.

  5. در بخش «مدیران جدید» ، آدرس ایمیل حساب سرویس افزونه Google Workspace مرتبط با برنامه چت خود را وارد کنید.

    آدرس ایمیل حساب سرویس در صفحه پیکربندی Chat API، در مسیر Connection settings > HTTP endpoint URL > Service Account Email قرار دارد:

    به پیکربندی API چت بروید

  6. در بخش «انتخاب یک نقش» ، Cloud Run > Cloud Run Service Invoker را انتخاب کنید.

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

برنامه چت آماده دریافت و پاسخ به پیام‌ها در چت است.

برنامه چت خود را آزمایش کنید

برای آزمایش برنامه چت خود، یک فضای پیام مستقیم با برنامه چت باز کنید و پیامی ارسال کنید:

  1. با استفاده از حساب Google Workspace که هنگام اضافه کردن خود به عنوان یک آزمایشگر مورد اعتماد ارائه دادید، Google Chat را باز کنید.

    به گوگل چت بروید

  2. روی گپ جدید کلیک کنید.
  3. در فیلد «افزودن ۱ یا چند نفر» ، نام برنامه چت خود را تایپ کنید.
  4. برنامه چت خود را از بین نتایج انتخاب کنید. یک پیام مستقیم باز می‌شود.

  5. در پیام مستقیم جدید با برنامه، عبارت Hello را تایپ کنید و enter را فشار دهید.

پیام برنامه چت حاوی کارتی است که نام و تصویر آواتار فرستنده را نمایش می‌دهد، همانطور که در تصویر زیر نشان داده شده است:

برنامه چت با کارتی که نام نمایشی و تصویر آواتار فرستنده را نشان می‌دهد، پاسخ می‌دهد.

برای افزودن آزمایش‌کنندگان مورد اعتماد و کسب اطلاعات بیشتر در مورد آزمایش ویژگی‌های تعاملی، به بخش «آزمایش ویژگی‌های تعاملی برای برنامه‌های Google Chat» مراجعه کنید.

عیب‌یابی

وقتی یک برنامه یا کارت چت گوگل خطایی را برمی‌گرداند، رابط چت پیامی با عنوان «مشکلی پیش آمده است» یا «درخواست شما قابل پردازش نیست» نمایش می‌دهد. گاهی اوقات رابط کاربری چت هیچ پیام خطایی را نمایش نمی‌دهد، اما برنامه یا کارت چت نتیجه غیرمنتظره‌ای را ایجاد می‌کند؛ برای مثال، ممکن است پیام کارت ظاهر نشود.

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

تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این آموزش، توصیه می‌کنیم پروژه Cloud را حذف کنید.

  1. در کنسول گوگل کلود، به صفحه مدیریت منابع بروید. منو > مدیریت و دسترسی به منابع (IAM & Admin) > مدیریت منابع (Manage Resources) کلیک کنید.

    به مدیریت منابع بروید

  2. در لیست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی «حذف کلیک کنید.
  3. در کادر محاوره‌ای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن (Shut down) کلیک کنید.