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

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

این صفحه نحوه ساخت افزونه Google Workspace را توضیح می‌دهد که در چت Google با استفاده از سرویس HTTP کار می‌کند. در Google Chat، افزونه‌ها به عنوان برنامه‌های Google Chat برای کاربران ظاهر می‌شوند. برای کسب اطلاعات بیشتر، به نمای کلی Extend Google Chat مراجعه کنید.

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

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

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

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

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

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

اهداف

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

پیش نیازها

یک حساب 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 را فعال کنید.
همچنین باید Google Workspace Add-ons API را فعال کنید، اما نمی‌توانید از این API برای ایجاد و مدیریت استقرار برنامه Chat استفاده کنید. برای جزئیات، محدودیت ها و مسائل شناخته شده را ببینید.
API ها را فعال کنید

ایجاد و استقرار یک تابع ابری

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

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

Node.js

در کنسول Google Cloud، به صفحه Cloud Functions بروید:
به Cloud Functions بروید
مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.
روی Create Function کلیک کنید.
در صفحه ایجاد تابع، تابع خود را تنظیم کنید:
1. در Environment ، Cloud Run Function را انتخاب کنید.
2. در نام تابع ، AddOnChatApp وارد کنید.
3. در منطقه ، یک منطقه را انتخاب کنید.
4. در بخش Authentication، Require authentication را انتخاب کنید.
5. روی Next کلیک کنید.
در Runtime ، جدیدترین نسخه Node.js را انتخاب کنید.
در کد منبع ، ویرایشگر درون خطی را انتخاب کنید.
در نقطه ورود ، متن پیش فرض را حذف کنید و avatarApp وارد کنید.

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

/**
 * Google Cloud 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
 */
exports.avatarApp = function 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 }
                    }]
                }]
            }
        }]
    }}}}});
};

روی Deploy کلیک کنید.

پایتون

در کنسول Google Cloud، به صفحه Cloud Functions بروید:
به Cloud Functions بروید
مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.
روی Create Function کلیک کنید.
در صفحه ایجاد تابع، تابع خود را تنظیم کنید:
1. در Environment ، Cloud Run Function را انتخاب کنید.
2. در نام تابع ، AddOnChatApp وارد کنید.
3. در منطقه ، یک منطقه را انتخاب کنید.
4. در بخش Authentication، Require authentication را انتخاب کنید.
5. روی Next کلیک کنید.
در Runtime ، جدیدترین نسخه پایتون را انتخاب کنید.
در کد منبع ، ویرایشگر درون خطی را انتخاب کنید.
در نقطه ورود ، متن پیش فرض را حذف کرده و avatar_app وارد کنید.

محتوای 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 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 }
                    }]
                }]
            }
        }]
    }}}}}

روی Deploy کلیک کنید.

جاوا

در کنسول Google Cloud، به صفحه Cloud Functions بروید:
به Cloud Functions بروید
مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.
روی Create Function کلیک کنید.
در صفحه ایجاد تابع، تابع خود را تنظیم کنید:
1. در Environment ، Cloud Run Function را انتخاب کنید.
2. در نام تابع ، AddOnChatApp وارد کنید.
3. در منطقه ، یک منطقه را انتخاب کنید.
4. در بخش Authentication، Require authentication را انتخاب کنید.
5. روی Next کلیک کنید.
در Runtime ، جدیدترین نسخه جاوا را انتخاب کنید.
در کد منبع ، ویرایشگر درون خطی را انتخاب کنید.
در نقطه ورود ، متن پیش فرض را حذف کرده و وارد AvatarApp شوید.
نام فایل پیش‌فرض جاوا را به src/main/java/AvatarApp.java تغییر دهید.

محتوای 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;
    }
}

کد زیر را جایگزین محتوای 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>

روی Deploy کلیک کنید.

صفحه جزئیات Cloud Functions باز می شود و عملکرد شما با دو نشانگر پیشرفت ظاهر می شود: یکی برای ساخت و دیگری برای سرویس. هنگامی که هر دو نشانگر پیشرفت ناپدید می شوند و با علامت چک جایگزین می شوند، عملکرد شما مستقر و آماده است.

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

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

در کنسول Google Cloud، به صفحه Cloud Run بروید:
به Cloud Run بروید
در لیست خدمات Cloud Run، کادر کنار عملکرد دریافت را انتخاب کنید. (روی خود تابع کلیک نکنید.)
روی Permissions کلیک کنید. پانل مجوزها باز می شود.
روی افزودن اصلی کلیک کنید.
در اصول جدید ، آدرس ایمیل حساب سرویس افزودنی Google Workspace مرتبط با پروژه خود را وارد کنید.
در انتخاب نقش ، Cloud Run > Cloud Run Invoker را انتخاب کنید.
روی ذخیره کلیک کنید.

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

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

در کنسول Google Cloud، روی منو > عملکردهای ابری کلیک کنید.
به Cloud Functions بروید
مطمئن شوید که پروژه ای که برای آن Cloud Functions را فعال کرده اید انتخاب شده باشد.
در لیست توابع، روی AddOnChatApp کلیک کنید.
روی تب Triggers کلیک کنید.
در زیر HTTPS ، URL را کپی کنید.
«Google Chat API» را جستجو کنید و روی Google Chat API کلیک کنید، سپس روی Manage کلیک کنید.
به Chat API بروید
روی Configuration کلیک کنید و برنامه Google Chat را راه اندازی کنید:
1. در نام برنامه ، Add-on Chat app وارد کنید.
2. در URL آواتار ، https://developers.google.com/chat/images/quickstart-app-avatar.png را وارد کنید.
3. در توضیحات ، Add-on Chat app وارد کنید.
4. در بخش عملکرد ، دریافت پیام های 1:1 و پیوستن به فضاها و مکالمات گروهی را انتخاب کنید.
5. در تنظیمات اتصال ، نشانی وب نقطه پایانی HTTP را انتخاب کنید و URL مربوط به راه‌انداز عملکرد Cloud را در کادر قرار دهید.
6. در Authentication Audience ، URL نقطه پایانی HTTP را انتخاب کنید.
7. در قسمت Visibility ، این برنامه Google Chat را برای افراد و گروه‌های خاصی در دامنه خود در دسترس قرار دهید را انتخاب کنید و آدرس ایمیل خود را وارد کنید.
8. در زیر گزارش‌ها ، 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 کلیک کنید تا پروژه حذف شود.