یک برنامه 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 را با کد زیر جایگزین کنید:
    /**
     * Google Cloud Run function that responds to messages sent from a
     * Google Chat space.
     *
     * @param {Object} req Request sent from Google Chat space
     * @param {Object} res Response to send back
     */
    import { http } from '@google-cloud/functions-framework';
    
    http('avatarApp', (req, res) => {
        if (req.method === 'GET' || !req.body.chat) {
            return res.send('Hello! This function is meant to be used ' +
                'in a Google Chat Space.');
        }
    
        // Stores the Google Chat event as a variable.
        const chatMessage = req.body.chat.messagePayload.message;
    
        // Replies with the sender's avatar in a card.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            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. محتویات فایل package.json را با کد زیر جایگزین کنید:
    {
      "name": "avatar-app",
      "version": "1.0.0",
      "description": "Google Chat Avatar App",
      "main": "index.js",
      "type": "module",
      "scripts": {
        "start": "node index.js"
      },
      "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
      }
    }
    
    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
    
    @functions_framework.http
    def avatar_app(req: flask.Request) -> Mapping[str, Any]:
        """Google Cloud Run Function that handles requests from Google Chat
    
        Args:
            flask.Request: the request
    
        Returns:
            Mapping[str, Any]: the response
        """
        if req.method == "GET":
            return "Hello! This function must be called from Google Chat."
    
        request_json = req.get_json(silent=True)
    
        # Stores the Google Chat event as a variable.
        chat_message = request_json["chat"]["messagePayload"]["message"]
    
        # Replies with the sender's avatar in a card.
        display_name = chat_message["sender"]["displayName"]
        avatar_url = chat_message["sender"]["avatarUrl"]
        return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
            "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 ، متن پیش‌فرض را حذف کرده و AvatarApp وارد کنید.
    2. فایل پیش‌فرض جاوا را به src/main/java/gcfv2/AvatarApp.java تغییر نام دهید.
    3. محتویات AvatarApp.java را با کد زیر جایگزین کنید:
    import java.util.List;
    
    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;
    
    public class AvatarApp implements HttpFunction {
        private static final Gson gson = new Gson();
    
        @Override
        public void service(HttpRequest request, HttpResponse response) throws Exception {
            JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);
            if (request.getMethod().equals("GET") || !body.has("chat")) {
                response.getWriter().write("Hello! This function is meant to be used " +
                    "in a Google Chat Space..");
                return;
            }
    
            // Stores the Google Chat event as a variable.
            JsonObject chatMessage = body.getAsJsonObject("chat")
                .getAsJsonObject("messagePayload").getAsJsonObject("message");
    
            // Replies with the sender's avatar in a card.
            String displayName = chatMessage.getAsJsonObject("sender").get("displayName").getAsString();
            String avatarUrl = chatMessage.getAsJsonObject("sender").get("avatarUrl").getAsString();
            Message message = createMessage(displayName, avatarUrl);
    
            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));
        }
    
        Message createMessage(String displayName, String avatarUrl) {
            GoogleAppsCardV1CardHeader cardHeader = new GoogleAppsCardV1CardHeader();
            cardHeader.setTitle(String.format("Hello %s!", displayName));
    
            GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
            textParagraph.setText("Your avatar picture: ");
    
            GoogleAppsCardV1Widget avatarWidget = new GoogleAppsCardV1Widget();
            avatarWidget.setTextParagraph(textParagraph);
    
            GoogleAppsCardV1Image image = new GoogleAppsCardV1Image();
            image.setImageUrl(avatarUrl);
    
            GoogleAppsCardV1Widget avatarImageWidget = new GoogleAppsCardV1Widget();
            avatarImageWidget.setImage(image);
    
            GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
            section.setWidgets(List.of(avatarWidget, avatarImageWidget));
    
            GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
            card.setName("Avatar Card");
            card.setHeader(cardHeader);
            card.setSections(List.of(section));
    
            CardWithId cardWithId = new CardWithId();
            cardWithId.setCardId("avatarCard");
            cardWithId.setCard(card);
    
            Message message = new Message();
            message.setText("Here's your avatar");
            message.setCardsV2(List.of(cardWithId));
    
            return message;
        }
    }
    
  5. محتویات 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.0.4</version>
            </dependency>
    
            <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
            <dependency>
                <groupId>com.google.code.gson</groupId>
                <artifactId>gson</artifactId>
                <version>2.9.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-rev20230115-2.0.0</version>
            </dependency>
        </dependencies>
    
        <!-- Required for Java functions in the inline editor -->
        <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) کلیک کنید.