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

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

با این معماری، شما 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 ایجاد و مستقر کنید.
  • برنامه را در چت منتشر کنید.
  • برنامه را تست کنید.

پیش‌نیازها

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

قبل از استفاده از APIهای گوگل، باید آنها را در یک پروژه گوگل کلود فعال کنید. می‌توانید یک یا چند API را در یک پروژه گوگل کلود فعال کنید.
  • در کنسول Google Cloud، APIهای Google Chat، Cloud Build API، 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. در فیلد نام سرویس ، quickstartchatapp وارد کنید.
    2. در لیست منطقه ، یک منطقه را انتخاب کنید.
    3. در لیست Runtime ، جدیدترین نسخه Node.js را انتخاب کنید.
    4. در بخش احراز هویت ، گزینه «احراز هویت الزامی» را انتخاب کنید.
    5. روی Create کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به تب Source هدایت می‌کند.
  4. در برگه منبع :

    1. در قسمت Entry point ، متن پیش‌فرض را حذف کرده و avatarApp وارد کنید.
    2. محتویات فایل index.js را با کد زیر جایگزین کنید:

      گره/avatar-app/index.js
      const functions = require('@google-cloud/functions-framework');
      
      // Command IDs (configure these in Google Chat API)
      const ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
      const HELP_COMMAND_ID = 2; // ID for the "Help" quick command
      
      /**
       * Google Cloud Function that handles HTTP requests from Google Chat.
       *
       * @param {Object} req - The HTTP request object sent from Google Chat.
       * @param {Object} res - The HTTP response object.
       */
      functions.http('avatarApp', (req, res) => {
        const event = req.body;
      
        if (event.appCommandMetadata) {
          handleAppCommands(event, res);
        } else {
          handleRegularMessage(event, res);
        }
      });
      
      /**
       * Handles slash and quick commands.
       *
       * @param {Object} event - The Google Chat event.
       * @param {Object} res - The HTTP response object.
       */
      function handleAppCommands(event, res) {
        const {appCommandId, appCommandType} = event.appCommandMetadata;
      
        switch (appCommandId) {
          case ABOUT_COMMAND_ID:
            return res.send({
              privateMessageViewer: event.user,
              text: 'The Avatar app replies to Google Chat messages.'
            });
          case HELP_COMMAND_ID:
            return res.send({
              privateMessageViewer: event.user,
              text: 'The Avatar app replies to Google Chat messages.'
            });
        }
      }
      
      /**
       * Handles regular messages (not commands).
       *
       * @param {Object} event - The Google Chat event.
       * @param {Object} res - The HTTP response object.
       */
      function handleRegularMessage(event, res) {
        const messageData = createMessage(event.user);
        res.send(messageData);
      }
      
      /**
       * Creates a card message with the user's avatar.
       *
       * @param {Object} user - The user who sent the message.
       * @param {string} user.displayName - The user's display name.
       * @param {string} user.avatarUrl - The URL of the user's avatar.
       * @return {Object} - The card message object.
       */
      function createMessage({displayName, 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}},
                ],
              }],
            },
          }],
        };
      }

    3. روی ذخیره و استقرار مجدد کلیک کنید.

پایتون

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

    به Cloud Run بروید

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

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

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

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

    1. در قسمت Entry point ، متن پیش‌فرض را حذف کرده و avatar_app وارد کنید.
    2. محتویات main.py را با کد زیر جایگزین کنید:

      پایتون/avatar-app/main.py
      from typing import Any, Mapping
      
      import flask
      import functions_framework
      
      # Command IDs (configure these in Google Chat API)
      ABOUT_COMMAND_ID = 1  # ID for the "/about" slash command
      HELP_COMMAND_ID = 2  # ID for the "Help" quick command
      
      
      @functions_framework.http
      def avatar_app(req: flask.Request) -> Mapping[str, Any]:
          """Google Cloud Function that handles HTTP requests from Google Chat.
      
          Args:
              flask.Request: the request
      
          Returns:
              Mapping[str, Any]: the response
          """
          event = req.get_json(silent=True)
      
          if event and "appCommandMetadata" in event:
              return handle_app_commands(event)
          else:
              return handle_regular_message(event)
      
      
      def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
          """Handles slash and quick commands.
      
          Args:
              Mapping[str, Any] event: The Google Chat event.
      
          Returns:
              Mapping[str, Any]: the response
          """
          app_command_id = event["appCommandMetadata"]["appCommandId"]
      
          if app_command_id == ABOUT_COMMAND_ID:
              return {
                  "privateMessageViewer": event["user"],
                  "text": "The Avatar app replies to Google Chat messages.",
              }
          elif app_command_id == HELP_COMMAND_ID:
              return {
                  "privateMessageViewer": event["user"],
                  "text": "The Avatar app replies to Google Chat messages.",
              }
          return {}
      
      
      
      
      def handle_regular_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
          """Handles regular messages (not commands).
      
          Args:
              Mapping[str, Any] event: The Google Chat event.
      
          Returns:
              Mapping[str, Any]: the response
          """
      
          if not event or "user" not in event:
              return "Invalid request."
      
          message_data = create_message(event["user"])
          return message_data
      
      
      def create_message(user: Mapping[str, Any]) -> Mapping[str, Any]:
          """Creates a card message with the user's avatar.
      
          Args:
              Mapping[str, Any] user: The user who sent the message.
      
          Returns:
              Mapping[str, Any]: a card with the user's avatar.
          """
          display_name = user.get("displayName", "")
          avatar_url = 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}},
                                  ]
                              }
                          ],
                      },
                  }
              ],
          }

    3. روی ذخیره و استقرار مجدد کلیک کنید.

جاوا

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

    به Cloud Run بروید

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

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

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

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

    1. در قسمت Entry point ، متن پیش‌فرض را حذف کرده و App وارد کنید.
    2. نام src/main/java/com/example/Example.java را به src/main/java/AvatarApp.java تغییر دهید.
    3. محتویات AvatarApp.java را با کد زیر جایگزین کنید:

      java/avatar-app/src/main/java/AvatarApp.java
      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.api.services.chat.v1.model.User;
      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 AvatarApp implements HttpFunction {
        private static final Gson gson = new Gson();
      
        // Command IDs (configure these in Google Chat API)
        private static final int ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
        private static final int HELP_COMMAND_ID = 2; // ID for the "Help" quick command
      
        @Override
        public void service(HttpRequest request, HttpResponse response) throws Exception {
          JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
      
          if (event.has("appCommandMetadata")) {
            handleAppCommands(event, response);
          } else {
            handleRegularMessage(event, response);
          }
        }
      
        /**
         * Handles slash and quick commands.
         *
         * @param event    The Google Chat event.
         * @param response The HTTP response object.
         */
        private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
          int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();
      
          switch (appCommandId) {
            case ABOUT_COMMAND_ID:
              Message aboutMessage = new Message();
              aboutMessage.setText("The Avatar app replies to Google Chat messages.");
              aboutMessage.setPrivateMessageViewer(new User()
                  .setName(event.getAsJsonObject("user").get("name").getAsString()));
              response.getWriter().write(gson.toJson(aboutMessage));
              return;
            case HELP_COMMAND_ID:
              Message helpMessage = new Message();
              helpMessage.setText("The Avatar app replies to Google Chat messages.");
              helpMessage.setPrivateMessageViewer(new User()
                  .setName(event.getAsJsonObject("user").get("name").getAsString()));
              response.getWriter().write(gson.toJson(helpMessage));
              return;
          }
        }
      
        /**
         * Handles regular messages (not commands).
         *
         * @param event    The Google Chat event.
         * @param response The HTTP response object.
         */
        private void handleRegularMessage(JsonObject event, HttpResponse response) throws Exception {
      
          if (!event.has("user")) {
            response.getWriter().write("Invalid request.");
            return;
          }
      
          JsonObject user = event.getAsJsonObject("user");
          String displayName = user.has("displayName") ? user.get("displayName").getAsString() : "";
          String avatarUrl = user.has("avatarUrl") ? user.get("avatarUrl").getAsString() : "";
          Message message = createMessage(displayName, avatarUrl);
          response.getWriter().write(gson.toJson(message));
        }
      
        /**
         * Creates a card message with the user's avatar.
         *
         * @param displayName The user's display name.
         * @param avatarUrl   The URL of the user's avatar.
         * @return The card message object.
         */
        private Message createMessage(String displayName, String avatarUrl) {
          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)))))))));
        }
      }

    4. محتویات pom.xml را با کد زیر جایگزین کنید:

      java/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/maven-v4_0_0.xsd">
        <modelVersion>4.0.0</modelVersion>
      
        <groupId>gcfv2</groupId>
        <artifactId>avatar-app</artifactId>
        <version>0.0.1</version>
        <name>Avatar App</name>
      
        <properties>
          <maven.compiler.release>21</maven.compiler.release>
        </properties>
      
        <dependencies>
          <dependency>
            <groupId>com.google.cloud.functions</groupId>
            <artifactId>functions-framework-api</artifactId>
            <version>1.1.4</version>
          </dependency>
      
          <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
          <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.12.1</version>
          </dependency>
      
          <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->
          <dependency>
            <groupId>com.google.apis</groupId>
            <artifactId>google-api-services-chat</artifactId>
            <version>v1-rev20250116-2.0.0</version>
          </dependency>
      
        </dependencies>
      
      </project>

    5. روی ذخیره و استقرار مجدد کلیک کنید.

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

برای اینکه به گوگل چت اجازه دهید تابع شما را فراخوانی کند، حساب سرویس گوگل چت را با نقش Cloud Run Invoker اضافه کنید.

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

    به Cloud Run بروید

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

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

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

  5. در قسمت New principals ، chat@system.gserviceaccount.com وارد کنید.

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

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

پیکربندی برنامه چت

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

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

    به Cloud Run بروید

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

  2. در لیست سرویس‌ها، روی quickstartchatapp کلیک کنید.

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

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

    به API چت بروید

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

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

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

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

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

  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) کلیک کنید.