تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إنشاء تطبيق Google Chat يستخدم بروتوكول HTTP

توضّح هذه الصفحة كيفية إنشاء إضافة في Google Workspace تعمل في Google Chat باستخدام خدمة HTTP.

يوضّح لك دليل البدء السريع هذا كيفية إنشاء خدمة HTTP باستخدام خدمات Google Cloud. لإنشاء تطبيق Chat، عليك كتابة ونشر دالة Cloud يستخدمها تطبيق Chat للردّ على رسالة المستخدم.

باستخدام بنية HTTP الأساسية، يمكنك إعداد Chat للدمج مع Google Cloud أو خادم محلي باستخدام HTTP، كما هو موضّح في الرسم البياني التالي:

بنية تطبيق Chat يستخدم خدمة ويب على خادم مُثبَّت على أجهزة الشركة

في الرسم البياني السابق، يتضمّن تفاعل المستخدم مع تطبيق HTTP Chat تدفّق المعلومات التالي:

يرسل مستخدم رسالة في Chat إلى تطبيق Chat، إما في رسالة مباشرة أو في مساحة Chat.
يتم إرسال طلب HTTP إلى خادم ويب، وهو إما نظام مستند إلى السحابة الإلكترونية أو نظام محلي يتضمّن منطق تطبيق Chat.
يمكن دمج منطق تطبيق Chat اختياريًا مع خدمات Google Workspace (مثل "تقويم Google" و"جداول بيانات Google") أو خدمات Google الأخرى (مثل "خرائط Google" وYouTube وVertex AI) أو خدمات الويب الأخرى (مثل نظام إدارة المشاريع أو أداة إصدار التذاكر).
يرسل خادم الويب استجابة HTTP إلى خدمة تطبيق Chat في Chat.
يتم تسليم الرد إلى المستخدم.
يمكن لتطبيق Chat اختياريًا استدعاء واجهة برمجة تطبيقات Chat لنشر الرسائل بشكل غير متزامن أو تنفيذ عمليات أخرى.

تتيح لك هذه البنية المرونة في استخدام المكتبات والمكوّنات الحالية المتوفّرة في نظامك، لأنّه يمكن تصميم تطبيقات الدردشة هذه باستخدام لغات برمجة مختلفة.

الأهداف

إعداد البيئة
أنشئ دالة Cloud Function ونشِرها.
ضبط إحدى إضافات Google Workspace لتطبيق Chat
اختبار التطبيق

المتطلبات الأساسية

حساب Google Workspace من إصدار Business أو Enterprise مع إذن الوصول إلى Google Chat
مشروع على Google Cloud تم تفعيل الفوترة فيه للتأكّد من تفعيل الفوترة في مشروع حالي، يُرجى الاطّلاع على التأكّد من حالة الفوترة في مشاريعك. لإنشاء مشروع وإعداد الفوترة، يُرجى الاطّلاع على إنشاء مشروع على Google Cloud.

إعداد البيئة

قبل استخدام واجهات Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

في Google Cloud Console، فعِّل Cloud Build API وCloud Functions API وCloud Pub/Sub API وCloud Logging API وArtifact Registry API وCloud Run API.

تفعيل واجهات برمجة التطبيقات

إنشاء دالة Cloud Function ونشرها

أنشئ ونفِّذ Cloud Function تنشئ بطاقة Chat تتضمّن الاسم المعروض للمرسل وصورة الأفاتار. عندما يتلقّى تطبيق Chat رسالة، ينفّذ الدالة ويردّ بالبطاقة.

لإنشاء الدالة ونشرها لتطبيق Chat، يُرجى إكمال الخطوات التالية:

Node.js

في Google Cloud Console، انتقِل إلى صفحة Cloud Functions:

الانتقال إلى Cloud Functions

تأكَّد من اختيار مشروع تطبيق Chat.
انقر على إنشاء دالة.
في صفحة "إنشاء دالة"، اضبط دالتك على النحو التالي:
1. في البيئة، اختَر وظيفة Cloud Run.
2. في حقل اسم الدالة، أدخِل AddOnChatApp.
3. في المنطقة، اختَر منطقة.
4. ضمن "المصادقة"، اختَر طلب المصادقة.
5. انقر على التالي.
في وقت التشغيل، اختَر أحدث إصدار من 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 }
                    }]
                }]
            }
        }]
    }}}}});
};

انقر على نشر.

Python

في Google Cloud Console، انتقِل إلى صفحة Cloud Functions:

الانتقال إلى Cloud Functions

تأكَّد من اختيار مشروع تطبيق Chat.
انقر على إنشاء دالة.
في صفحة "إنشاء دالة"، اضبط دالتك على النحو التالي:
1. في البيئة، اختَر وظيفة Cloud Run.
2. في حقل اسم الدالة، أدخِل AddOnChatApp.
3. في المنطقة، اختَر منطقة.
4. ضمن "المصادقة"، اختَر طلب المصادقة.
5. انقر على التالي.
في وقت التشغيل، اختَر أحدث إصدار من Python.
في رمز المصدر، اختَر المحرّر المضمّن.
في نقطة الدخول، احذف النص التلقائي وأدخِل 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 }
                    }]
                }]
            }
        }]
    }}}}}

انقر على نشر.

Java

في Google Cloud Console، انتقِل إلى صفحة Cloud Functions:

الانتقال إلى Cloud Functions

تأكَّد من اختيار مشروع تطبيق Chat.
انقر على إنشاء دالة.
في صفحة "إنشاء دالة"، اضبط دالتك على النحو التالي:
1. في البيئة، اختَر وظيفة Cloud Run.
2. في حقل اسم الدالة، أدخِل AddOnChatApp.
3. في المنطقة، اختَر منطقة.
4. ضمن "المصادقة"، اختَر طلب المصادقة.
5. انقر على التالي.
في وقت التشغيل، اختَر أحدث إصدار من Java.
في رمز المصدر، اختَر المحرّر المضمّن.
في نقطة الدخول، احذف النص التلقائي وأدخِل AvatarApp.
أعِد تسمية ملف Java التلقائي إلى 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>

انقر على نشر.

تُفتح صفحة تفاصيل Cloud Functions، وتظهر الدالة مع مؤشّرَي تقدّم، أحدهما خاص بالإنشاء والآخر خاص بالخدمة. عندما يختفي مؤشرا التقدم ويتم استبدالهما بعلامة اختيار، يعني ذلك أنّه تم نشر الدالة وأصبحت جاهزة.

ضبط الإضافة

بعد نشر Cloud Function، اتّبِع الخطوات التالية لإنشاء إضافة ونشر تطبيق Google Chat:

في وحدة تحكّم Google Cloud، انقر على "القائمة" > Cloud Functions.

الانتقال إلى Cloud Functions

تأكَّد من اختيار المشروع الذي فعّلت فيه Cloud Functions.
في قائمة الدوال، انقر على AddOnChatApp.
انقر على علامة التبويب العوامل المشغِّلة.
ضِمن HTTPS، انسخ عنوان URL.
ابحث عن "Google Chat API" وانقر على Google Chat API، ثم انقر على إدارة.

الانتقال إلى Chat API
انقر على الإعداد وأعِدّ تطبيق Google Chat باتّباع الخطوات التالية:
1. في حقل اسم التطبيق، أدخِل Add-on Chat app.
2. في عنوان URL للأفاتار، أدخِل https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
3. في الوصف، أدخِل Add-on Chat app.
4. ضمن الوظائف، اختَر الانضمام إلى المساحات والمحادثات الجماعية.
5. ضمن إعدادات الاتصال، اختَر عنوان URL لنقطة نهاية HTTP والصِق عنوان URL الخاص بمشغّل Cloud Function في المربّع.
6. في الجمهور المستهدف للمصادقة، اختَر عنوان URL لنقطة نهاية HTTP.
7. ضمن مستوى الظهور، اختَر إتاحة تطبيق Google Chat هذا لأشخاص ومجموعات معيّنة في نطاقك وأدخِل عنوان بريدك الإلكتروني.
8. ضمن السجلات، اختَر تسجيل الأخطاء في خدمة تسجيل البيانات.
انقر على حفظ.

بعد ذلك، امنح تطبيق Chat الإذن بتفعيل Cloud Function.

منح Google Chat الإذن باستدعاء الدالة

لمنح إضافة Google Workspace الإذن بتفعيل وظيفتك، أضِف حساب خدمة إضافة Google Workspace مع دور مفعِّل Cloud Run.

في Google Cloud Console، انتقِل إلى صفحة Cloud Run:

الانتقال إلى Cloud Run
في قائمة خدمات Cloud Run، ضَع علامة في مربّع الاختيار بجانب الدالة التي تتلقّى البيانات. (لا تنقر على الدالة نفسها).
انقر على الأذونات. تفتح لوحة الأذونات.
انقر على إضافة مدير.
في المستخدمون الرئيسيون الجدد، أدخِل عنوان البريد الإلكتروني لحساب خدمة إضافة Google Workspace المرتبط بمشروعك. ابحث عن عنوان البريد الإلكتروني لحساب الخدمة ضمن إعدادات الاتصال > عنوان URL لنقطة نهاية HTTP > البريد الإلكتروني لحساب الخدمة في صفحة إعدادات Chat API:

الانتقال إلى إعدادات Chat API
في اختيار دور، اختَر Cloud Run > مستدعي Cloud Run.
انقر على حفظ.

تطبيق Chat جاهز لتلقّي الرسائل والردّ عليها.

اختبار تطبيق Chat

لاختبار تطبيق Chat، افتح مساحة رسالة مباشرة باستخدام تطبيق Chat وأرسِل رسالة:

افتح Google Chat باستخدام حساب Google Workspace الذي قدّمته عند إضافة نفسك كمختبِر موثوق به.

الانتقال إلى Google Chat
انقر على محادثة جديدة.
في حقل إضافة مستخدم واحد أو أكثر، اكتب اسم تطبيق Chat.
اختَر تطبيق Chat من النتائج. سيتم فتح رسالة مباشرة.

ملاحظة: إذا لم يظهر تطبيق Chat في قائمة النتائج، تأكَّد من تضمين حسابك على Google Workspace في إعدادات إمكانية الوصول في صفحة إعدادات Chat API في Google Cloud Console.
في الرسالة المباشرة الجديدة مع التطبيق، اكتب Hello واضغط على enter.

تحتوي الرسالة في تطبيق Chat على بطاقة تعرض اسم المرسل وصورة الأفاتار الخاصة به، كما هو موضّح في الصورة التالية:

تطبيق Chat يستجيب ببطاقة تعرض الاسم المعروض للمرسل وصورة الأفاتار

لإضافة مختبِرين موثوق بهم والتعرّف على مزيد من المعلومات حول اختبار الميزات التفاعلية، يُرجى الاطّلاع على مقالة اختبار الميزات التفاعلية لتطبيقات Google Chat.

تحديد المشاكل وحلّها

عندما يعرض تطبيق أو بطاقة في Google Chat خطأً، تعرض واجهة Chat رسالة تفيد بأنّه "حدث خطأ". أو "لم نتمكّن من معالجة طلبك". في بعض الأحيان، لا تعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن ينتج تطبيق Chat أو البطاقة نتيجة غير متوقّعة، مثلاً، قد لا تظهر رسالة البطاقة.

على الرغم من أنّه قد لا تظهر رسالة خطأ في واجهة مستخدم Chat، تتوفّر رسائل خطأ وصفية وبيانات سجلّات لمساعدتك في إصلاح الأخطاء عند تفعيل تسجيل الأخطاء لتطبيقات Chat. للحصول على مساعدة في عرض الأخطاء وتصحيحها وتحديد المشاكل فيها، يُرجى الاطّلاع على تحديد مشاكل Google Chat وحلّها.

تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بحذف مشروع Cloud.

تنبيه: يؤدي حذف مشروع إلى ما يلي:

يتم حذف كل المحتوى في المشروع. إذا كنت قد استخدمت مشروعًا حاليًا لهذا البرنامج التعليمي، سيؤدي حذفه إلى حذف أي عمل آخر أنجزته في المشروع.
فقدان أرقام تعريف المشاريع المخصّصة: عند إنشاء هذا المشروع، ربما أنشأت معرّف مشروع مخصّصًا تريد استخدامه في المستقبل. للحفاظ على عناوين URL التي تستخدم رقم تعريف المشروع، مثل عنوان URL على appspot.com، احذف الموارد المحدّدة داخل المشروع بدلاً من حذف المشروع بأكمله.

إذا كنت تخطّط لاستكشاف العديد من البرامج التعليمية وأدلة البدء السريع، يمكن أن يساعدك إعادة استخدام المشاريع في تجنُّب تجاوز حدود حصص المشاريع.

في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد. انقر على القائمة > إدارة الهوية وإمكانية الوصول والمشرف > إدارة الموارد.
الانتقال إلى "إدارة الموارد"
في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف .
في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.