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

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

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

بنية تطبيق Chat باستخدام خدمة ويب على خادم محلي

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

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

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

الأهداف

  • إعداد البيئة
  • أنشئ دالة Cloud Run ونشرها.
  • انشر التطبيق في Chat.
  • اختبِر التطبيق.

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

إعداد البيئة

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

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

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

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

Node.js

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

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

    تأكَّد من اختيار مشروع تطبيق Chat.

  2. انقر على كتابة دالة.

  3. في صفحة إنشاء خدمة، يمكنك إعداد وظيفتك باتّباع الخطوات التالية:

    1. في حقل اسم الخدمة، أدخِل quickstartchatapp.
    2. في قائمة المنطقة، اختَر منطقة.
    3. في قائمة وقت التشغيل، اختَر أحدث إصدار من Node.js.
    4. في قسم المصادقة، اختَر طلب المصادقة.
    5. انقر على إنشاء وانتظِر إلى أن تنتهي خدمة Cloud Run من إنشاء الخدمة. تعيد وحدة التحكّم توجيهك إلى علامة التبويب المصدر.
  4. في علامة التبويب المصدر:

    1. في نقطة الدخول، احذف النص التلقائي وأدخِل avatarApp.
    2. استبدِل محتوى index.js بالرمز التالي:

      node/avatar-app/index.js
      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}},
                ],
              }],
            },
          }],
        };
      }

    3. انقر على حفظ وإعادة نشر.

Python

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

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

    تأكَّد من اختيار مشروع تطبيق Chat.

  2. انقر على كتابة دالة.

  3. في صفحة إنشاء خدمة، يمكنك إعداد وظيفتك باتّباع الخطوات التالية:

    1. في حقل اسم الخدمة، أدخِل quickstartchatapp.
    2. في قائمة المنطقة، اختَر منطقة.
    3. في قائمة وقت التشغيل، اختَر أحدث إصدار من Python.
    4. في قسم المصادقة، اختَر طلب المصادقة.
    5. انقر على إنشاء وانتظِر إلى أن تنتهي خدمة Cloud Run من إنشاء الخدمة. تعيد وحدة التحكّم توجيهك إلى علامة التبويب المصدر.
  4. في علامة التبويب المصدر:

    1. في نقطة الدخول، احذف النص التلقائي وأدخِل avatar_app.
    2. استبدِل محتوى main.py بالرمز التالي:

      python/avatar-app/main.py
      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}},
                                  ]
                              }
                          ],
                      },
                  }
              ],
          }

    3. انقر على حفظ وإعادة نشر.

Java

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

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

    تأكَّد من اختيار مشروع تطبيق Chat.

  2. انقر على كتابة دالة.

  3. في صفحة إنشاء خدمة، يمكنك إعداد وظيفتك باتّباع الخطوات التالية:

    1. في حقل اسم الخدمة، أدخِل quickstartchatapp.
    2. في قائمة المنطقة، اختَر منطقة.
    3. في قائمة وقت التشغيل، اختَر أحدث إصدار من Java.
    4. في قسم المصادقة، اختَر طلب المصادقة.
    5. انقر على إنشاء وانتظِر إلى أن تنتهي خدمة Cloud Run من إنشاء الخدمة. تعيد وحدة التحكّم توجيهك إلى علامة التبويب المصدر.
  4. في علامة التبويب المصدر:

    1. في نقطة الدخول، احذف النص التلقائي وأدخِل App.
    2. أعِد تسمية src/main/java/com/example/Example.java إلى src/main/java/AvatarApp.java.
    3. استبدِل محتوى AvatarApp.java بالرمز التالي:

      java/avatar-app/src/main/java/AvatarApp.java
      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)))))))));
        }
      }

    4. استبدِل محتوى pom.xml بالرمز التالي:

      java/avatar-app/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/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>

    5. انقر على حفظ وإعادة نشر.

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

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

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

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

  2. في قائمة خدمات Cloud Run، ضَع علامة في مربّع الاختيار بجانب الدالة التي تتلقّى البيانات. (لا تنقر على الدالة نفسها).

  3. انقر على الأذونات. تفتح لوحة الأذونات.

  4. انقر على إضافة كيان أساسي.

  5. في الأعضاء الجدد، أدخِل chat@system.gserviceaccount.com.

  6. في اختيار دور، اختَر Cloud Run > مستدعي Cloud Run.

  7. انقر على حفظ.

ضبط إعدادات تطبيق Chat

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

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

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

    تأكَّد من اختيار المشروع الذي فعّلت فيه Cloud Run.

  2. في قائمة الخدمات، انقر على quickstartchatapp.

  3. في صفحة تفاصيل الخدمة، انسخ عنوان URL الخاص بالدالة.

  4. ابحث عن "واجهة برمجة تطبيقات Google Chat" وانقر على واجهة برمجة تطبيقات Google Chat، ثم انقر على إدارة.

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

  5. انقر على الإعداد وأعِدّ تطبيق Google Chat باتّباع الخطوات التالية:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تَنظيم

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

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

    الانتقال إلى "إدارة الموارد"

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