این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

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

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

اهداف

محیط خود را تنظیم کنید.
ایجاد و استقرار تابع Cloud Run.
برنامه را در چت منتشر کنید.
برنامه را تست کنید.

پیش نیازها

یک حساب Google Workspace تجاری یا سازمانی با دسترسی به Google Chat .
یک پروژه Google Cloud با فعال کردن صورت‌حساب. برای بررسی فعال بودن صورت‌حساب پروژه موجود، به تأیید وضعیت صورت‌حساب پروژه‌های خود مراجعه کنید. برای ایجاد پروژه و تنظیم صورت‌حساب، به ایجاد پروژه Google Cloud مراجعه کنید.

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

قبل از استفاده از Google API، باید آنها را در پروژه Google Cloud روشن کنید. می‌توانید یک یا چند API را در یک پروژه Google Cloud روشن کنید.

در کنسول Google Cloud، Google Chat API، Cloud Build API، Cloud Functions API، Cloud Pub/Sub API، Cloud Logging API، Artifact Registry API، و Cloud Run API را فعال کنید.
API ها را فعال کنید

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

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

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

Node.js

در کنسول Google Cloud، به صفحه Cloud Run بروید:
به Cloud Run بروید
مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.
روی نوشتن یک تابع کلیک کنید.
در صفحه ایجاد سرویس ، عملکرد خود را تنظیم کنید:
1. در قسمت Service name ، quickstartchatapp وارد کنید.
2. در لیست منطقه ، یک منطقه را انتخاب کنید.
3. در لیست Runtime ، جدیدترین نسخه Node.js را انتخاب کنید.
4. در بخش Authentication ، Require authentication را انتخاب کنید.
5. روی Create کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به تب Source هدایت می کند.

در تب منبع :

در نقطه ورود ، متن پیش فرض را حذف کنید و avatarApp وارد کنید.

کد زیر را جایگزین محتوای index.js کنید:

node/avatar-app/index.js

در GitHub مشاهده کنید

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}},
          ],
        }],
      },
    }],
  };
}

روی Save و redeploy کلیک کنید.

پایتون

در کنسول Google Cloud، به صفحه Cloud Run بروید:
به Cloud Run بروید
مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.
روی نوشتن تابع کلیک کنید.
در صفحه ایجاد سرویس ، عملکرد خود را تنظیم کنید:
1. در قسمت Service name ، quickstartchatapp وارد کنید.
2. در لیست منطقه ، یک منطقه را انتخاب کنید.
3. در لیست Runtime ، جدیدترین نسخه پایتون را انتخاب کنید.
4. در بخش Authentication ، Require authentication را انتخاب کنید.
5. روی Create کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به تب Source هدایت می کند.

در تب منبع :

در نقطه ورود ، متن پیش فرض را حذف کرده و avatar_app وارد کنید.

محتوای main.py را با کد زیر جایگزین کنید:

python/avatar-app/main.py

در GitHub مشاهده کنید

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}},
                            ]
                        }
                    ],
                },
            }
        ],
    }

روی Save و redeploy کلیک کنید.

جاوا

در کنسول Google Cloud، به صفحه Cloud Run بروید:
به Cloud Run بروید
مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.
روی نوشتن تابع کلیک کنید.
در صفحه ایجاد سرویس ، عملکرد خود را تنظیم کنید:
1. در قسمت Service name ، quickstartchatapp وارد کنید.
2. در لیست منطقه ، یک منطقه را انتخاب کنید.
3. در لیست Runtime ، جدیدترین نسخه جاوا را انتخاب کنید.
4. در بخش Authentication ، Require authentication را انتخاب کنید.
5. روی Create کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به تب Source هدایت می کند.

در تب منبع :

در نقطه ورود ، متن پیش فرض را حذف کرده و وارد App شوید.
src/main/java/com/example/Example.java را به src/main/java/AvatarApp.java تغییر نام دهید.

محتوای AvatarApp.java را با کد زیر جایگزین کنید:

java/avatar-app/src/main/java/AvatarApp.java

در GitHub مشاهده کنید

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

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

java/avatar-app/pom.xml

در GitHub مشاهده کنید

<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>

روی Save و redeploy کلیک کنید.

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

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

در کنسول Google Cloud، به صفحه Cloud Run بروید:
به Cloud Run بروید
در لیست خدمات Cloud Run، کادر کنار عملکرد دریافت را انتخاب کنید. (روی خود تابع کلیک نکنید.)
روی Permissions کلیک کنید. پانل مجوزها باز می شود.
روی افزودن اصلی کلیک کنید.
در New Principals ، chat@system.gserviceaccount.com را وارد کنید.
در انتخاب نقش ، Cloud Run > Cloud Run Invoker را انتخاب کنید.
روی ذخیره کلیک کنید.

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

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

در کنسول Google Cloud، به صفحه Cloud Run بروید:
به Cloud Run بروید
مطمئن شوید که پروژه ای که Cloud Run را برای آن فعال کرده اید انتخاب شده باشد.
در لیست خدمات، روی quickstartchatapp کلیک کنید.
در صفحه جزئیات سرویس ، URL تابع را کپی کنید.
«Google Chat API» را جستجو کنید و روی Google Chat API کلیک کنید، سپس روی Manage کلیک کنید.
به Chat API بروید
روی Configuration کلیک کنید و برنامه Google Chat را راه اندازی کنید:
1. Build this Chat app به عنوان یک افزونه Google Workspace را پاک کنید. یک گفتگو باز می شود که از شما می خواهد تأیید کنید. در گفتگو، روی Disable کلیک کنید.
2. در نام برنامه ، Quickstart App وارد کنید.
3. در URL آواتار ، https://developers.google.com/chat/images/quickstart-app-avatar.png را وارد کنید.
4. در توضیحات ، Quickstart app را وارد کنید.
5. در بخش Functionality ، Join spaces and group را انتخاب کنید.
6. در قسمت تنظیمات اتصال ، URL نقطه پایانی HTTP را انتخاب کنید.
7. در قسمت Triggers ، استفاده از یک URL مشترک نقطه پایانی HTTP برای همه راه‌اندازها را انتخاب کنید و URL مربوط به راه‌انداز تابع Cloud Run را در کادر قرار دهید.
8. در قسمت Visibility ، گزینه Make this Chat app برای افراد و گروه‌های خاص در دامنه خود را انتخاب کنید و آدرس ایمیل خود را وارد کنید.
9. در زیر گزارش‌ها ، Log errors to Logging را انتخاب کنید.
روی ذخیره کلیک کنید.

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

برنامه چت خود را تست کنید

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

Google Chat را با استفاده از حساب Google Workspace که هنگام اضافه کردن خود به عنوان آزمایش‌کننده معتمد ارائه کرده‌اید، باز کنید.
به Google Chat بروید
گپ جدید کلیک کنید.
در قسمت افزودن 1 یا چند نفر ، نام برنامه چت خود را تایپ کنید.
برنامه چت خود را از نتایج انتخاب کنید. یک پیام مستقیم باز می شود.
توجه: اگر برنامه Chat خود را در لیست نتایج نمی‌بینید، مطمئن شوید که حساب Google Workspace خود را در تنظیمات Visibility صفحه پیکربندی Chat API در کنسول Google Cloud قرار داده‌اید.
در پیام مستقیم جدید با برنامه، Hello را تایپ کرده و enter فشار دهید.

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

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

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

عیب یابی

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

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

پاک کن

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

احتیاط: حذف یک پروژه دارای اثرات زیر است:

همه چیز در پروژه حذف می شود. اگر از یک پروژه موجود برای این آموزش استفاده کرده اید، وقتی آن را حذف می کنید، هر کار دیگری را که در پروژه انجام داده اید نیز حذف می کنید.
شناسه های پروژه سفارشی گم می شوند. وقتی این پروژه را ایجاد کردید، ممکن است یک ID پروژه سفارشی ایجاد کرده باشید که می خواهید در آینده از آن استفاده کنید. برای حفظ URL هایی که از شناسه پروژه استفاده می کنند، مانند URL در appspot.com، به جای حذف کل پروژه، منابع انتخاب شده در داخل پروژه را حذف کنید.

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

در کنسول Google Cloud، به صفحه مدیریت منابع بروید. > IAM & Admin > Manage Resources کلیک کنید.
به Resource Manager بروید
در لیست پروژه، پروژه ای را که می خواهید حذف کنید انتخاب کنید و سپس روی حذف کلیک کنید.
در گفتگو، ID پروژه را تایپ کنید و سپس بر روی Shut down کلیک کنید تا پروژه حذف شود.

موضوعات مرتبط

برای افزودن ویژگی‌های بیشتر به برنامه چت، موارد زیر را ببینید:
معماری برنامه چت را انتخاب کنید
درخواست‌های Google Chat را تأیید کنید

یک برنامه HTTP Google Chat بسازید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

اهداف

پیش نیازها

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

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

Node.js

پایتون

جاوا

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

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

برنامه چت خود را تست کنید

عیب یابی

پاک کن

موضوعات مرتبط

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