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

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

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

باستخدام هذه البنية، يمكنك ضبط 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 API لنشر الرسائل بشكل غير متزامن أو تنفيذ عمليات أخرى، وذلك اختياريًا.

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

الأهداف

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

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

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

إعداد البيئة

قبل استخدام واجهات برمجة تطبيقات Google، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيقات واحدة أو أكثر في مشروع واحد على 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.

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

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

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

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

Node.js

في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Cloud Functions:

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

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

انقر على نشر.

Python

في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Cloud Functions:

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

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

انقر على نشر.

Java

في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Cloud Functions:

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

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

انقر على نشر.

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

تفويض Google Chat لاستدعاء الدالة

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

في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Cloud Run:

الانتقال إلى Cloud Run
في قائمة خدمات Cloud Run، ضَع علامة في مربّع الاختيار بجانب وظيفة الاستقبال. (لا تنقر على الدالة نفسها).
انقر على الأذونات. ستفتح لوحة الأذونات.
انقر على إضافة جهة أساسية.
في العناصر الرئيسية الجديدة، أدخِل chat@system.gserviceaccount.com.
في اختيار دور، اختَر Cloud Run > Cloud Run Invoker.
انقر على حفظ.

نشر التطبيق في Google Chat

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

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

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

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

الانتقال إلى Chat API
انقر على الإعداد وفعِّل تطبيق Google Chat:
1. في حقل اسم التطبيق، أدخِل Quickstart App.
2. في عنوان URL للصورة الرمزية، أدخِل https://developers.google.com/chat/images/quickstart-app-avatar.png.
3. في الوصف، أدخِل Quickstart app.
4. ضمن الوظيفة، اختَر تلقّي رسائل بين شخصَين و الانضمام إلى المساحات والمحادثات الجماعية.
5. ضمن إعدادات الاتصال، اختَر عنوان URL لنقطة نهاية HTTP والصِق عنوان URL لملف بدء Cloud Function في المربّع.

انقر على حفظ.

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

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

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

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

الانتقال إلى Google Chat

انقر على محادثة جديدة.

في حقل إضافة مستخدم واحد أو أكثر، اكتب اسم تطبيق Chat.

اختَر تطبيق Chat من النتائج. ستظهر رسالة مباشرة.

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

في الرسالة المباشرة الجديدة مع التطبيق، اكتب Hello واضغط على enter.

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

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

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

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

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

تَنظيم

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

ملاحظة: يؤدي حذف مشروع إلى النتائج التالية:

يتم حذف كل المحتوى في المشروع. إذا استخدمت مشروعًا حاليًا في هذا الدليل التعليمي، سيؤدي حذفه إلى حذف أي عمل آخر أجريته في المشروع.

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

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

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

في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف .

في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.

مواضيع ذات صلة

لإضافة المزيد من الميزات إلى تطبيق Chat، يُرجى الاطّلاع على الخطوات التالية:

إنشاء رسائل بطاقات تفاعلية

الردّ على الأوامر التي تبدأ بشرطة مائلة

فتح مربّعات الحوار والردّ عليها

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

التحقّق من الطلبات الواردة من Google Chat