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

توضّح هذه الصفحة كيفية إنشاء تطبيق HTTP Chat. تتوفّر طرق مختلفة لتنفيذ هذه البنية. على Google Cloud، يمكنك استخدام Cloud Functions وCloud Run وApp Engine. في مرحلة البدء السريع هذه، يمكنك كتابة دالة Cloud ونشرها التي يستخدمها تطبيق 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 API لنشر الرسائل بشكل غير متزامن أو تنفيذ عمليات أخرى.

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

الأهداف

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

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

  • حساب Google Workspace يمكنه الوصول إلى Google Chat في مؤسسة Google Workspace تسمح باستدعاءات وظائف Google Cloud التي لم تتم مصادقتها.

إعداد البيئة

قبل استخدام Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيقات واحدة أو أكثر في مشروع واحد على Google Cloud.
  • في Google Cloud Console، فعِّل واجهة برمجة التطبيقات Google Chat API وCloud Build API وCloud Functions API وCloud Pub/Sub API وCloud Logging API وArtifact Registry API وواجهة برمجة التطبيقات Cloud Run.

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

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

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

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

Node.js

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

    الانتقال إلى دوال Cloud

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

  2. انقر على إنشاء دالة.

  3. في صفحة "إنشاء دالة"، قم بإعداد الدالة:

    1. في البيئة، اختَر الجيل الثاني.
    2. في اسم الدالة، أدخِل QuickStartChatApp.
    3. في المنطقة، اختَر منطقة.
    4. ضمن "المصادقة"، اختَر السماح بعمليات الاستدعاء التي لم تتم مصادقتها.
    5. انقر على التالي.
  4. في وقت التشغيل، اختَر Node.js 20.

  5. في رمز المصدر، اختَر المحرّر المضمّن.

  6. في نقطة الإدخال، احذف النص التلقائي وأدخِل helloChat.

  7. استبدِل محتوى index.js بالرمز التالي:

    العقدة/avatar-app/index.js
    /**
     * Google Cloud Function that responds to messages sent from a
     * Google Chat room.
     *
     * @param {Object} req Request sent from Google Chat room
     * @param {Object} res Response to send back
     */
    exports.helloChat = function helloChat(req, res) {
      if (req.method === 'GET' || !req.body.message) {
        res.send('Hello! This function is meant to be used in a Google Chat ' +
          'Room.');
      }
    
      const sender = req.body.message.sender.displayName;
      const image = req.body.message.sender.avatarUrl;
    
      const data = createMessage(sender, image);
    
      res.send(data);
    };
    
    /**
     * Creates a card with two widgets.
     * @param {string} displayName the sender's display name
     * @param {string} imageUrl the URL for the sender's avatar
     * @return {Object} a card with the user's avatar.
     */
    function createMessage(displayName, imageUrl) {
      const cardHeader = {
        title: `Hello ${displayName}!`,
      };
    
      const avatarWidget = {
        textParagraph: {text: 'Your avatar picture: '},
      };
    
      const avatarImageWidget = {
        image: {imageUrl},
      };
    
      const avatarSection = {
        widgets: [
          avatarWidget,
          avatarImageWidget,
        ],
      };
    
      return {
        text: 'Here\'s your avatar',
        cardsV2: [{
          cardId: 'avatarCard',
          card: {
            name: 'Avatar Card',
            header: cardHeader,
            sections: [avatarSection],
          }
        }],
      };
    }

  8. انقر على نشر.

Python

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

    الانتقال إلى دوال Cloud

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

  2. انقر على إنشاء دالة.

  3. في صفحة "إنشاء دالة"، قم بإعداد الدالة:

    1. في اسم الدالة، أدخِل QuickStartChatApp.
    2. في نوع المشغِّل، اختَر HTTP.
    3. ضمن "المصادقة"، اختَر السماح بعمليات الاستدعاء التي لم تتم مصادقتها.
    4. انقر على حفظ.
    5. انقر على التالي.
  4. في وقت التشغيل، اختر Python 3.10.

  5. في رمز المصدر، اختَر المحرّر المضمّن.

  6. في نقطة الإدخال، احذف النص التلقائي وأدخِل hello_chat.

  7. استبدِل محتوى main.py بالرمز التالي:

    python/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    
    # Google Cloud Function that responds to messages sent in
    # Google Chat.
    #
    # @param {Object} req Request sent from Google Chat.
    # @param {Object} res Response to send back.
    @functions_framework.http
    def hello_chat(req: flask.Request) -> Mapping[str, Any]:
      if req.method == "GET":
        return "Hello! This function must be called from Google Chat."
    
      request_json = req.get_json(silent=True)
    
      display_name = request_json["message"]["sender"]["displayName"]
      avatar = request_json["message"]["sender"]["avatarUrl"]
    
      response = create_message(name=display_name, image_url=avatar)
    
      return response
    
    
    # Creates a card with two widgets.
    # @param {string} name the sender's display name.
    # @param {string} image_url the URL for the sender's avatar.
    # @return {Object} a card with the user's avatar.
    def create_message(name: str, image_url: str) -> Mapping[str, Any]:
      avatar_image_widget = {"image": {"imageUrl": image_url}}
      avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
      avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}
    
      header = {"title": f"Hello {name}!"}
    
      cards = {
          "text": "Here's your avatar",
          "cardsV2": [
              {
                  "cardId": "avatarCard",
                  "card": {
                      "name": "Avatar Card",
                      "header": header,
                      "sections": [avatar_section],
                  },
              }
          ]
      }
    
      return cards

  8. انقر على نشر.

Java

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

    الانتقال إلى دوال Cloud

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

  2. انقر على إنشاء دالة.

  3. في صفحة "إنشاء دالة"، قم بإعداد الدالة:

    1. في اسم الدالة، أدخِل QuickStartChatApp.
    2. في نوع المشغِّل، اختَر HTTP.
    3. ضمن "المصادقة"، اختَر السماح بعمليات الاستدعاء التي لم تتم مصادقتها.
    4. انقر على حفظ.
    5. انقر على التالي.
  4. في وقت التشغيل، اختر Java 11.

  5. في رمز المصدر، اختَر المحرّر المضمّن.

  6. في نقطة الإدخال، احذف النص التلقائي وأدخِل HelloChat.

  7. إعادة تسمية src/main/java/com/example/Example.java إلى src/main/java/HelloChat.java.

  8. استبدِل محتوى HelloChat.java بالرمز التالي:

    java/avatar-app/src/main/java/HelloChat.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.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 HelloChat 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("message")) {
          response.getWriter().write("Hello! This function must be called from Google Chat.");
          return;
        }
    
        JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
        String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
        String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
        Message message = createMessage(displayName, avatarUrl);
    
        response.getWriter().write(gson.toJson(message));
      }
    
      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("previewLink");
        cardWithId.setCard(card);
    
        Message message = new Message();
        message.setText("Here's your avatar");
        message.setCardsV2(List.of(cardWithId));
    
        return message;
      }
    }

  9. استبدِل محتوى 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/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
    
      <groupId>cloudfunctions</groupId>
      <artifactId>http-function</artifactId>
      <version>1.0-SNAPSHOT</version>
    
      <properties>
        <maven.compiler.target>11</maven.compiler.target>
        <maven.compiler.source>11</maven.compiler.source>
      </properties>
    
      <dependencies>
        <dependency>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>functions-framework-api</artifactId>
          <version>1.0.1</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 11 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>

  10. انقر على نشر.

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

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

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

  1. في Google Cloud Console، انقر على رمز القائمة > دوال Cloud.

    الانتقال إلى دوال Cloud

    احرص على اختيار المشروع الذي فعّلت دوال السحابة له.

  2. في قائمة الدوال، انقر على QuickStartChatApp.

  3. في صفحة تفاصيل الدالة، انقر على مشغّل.

  4. ضمن عنوان URL للمشغِّل، انسخ عنوان URL.

  5. ابحث عن "Google Chat API" وانقر على Google Chat API، ثم انقر على إدارة.

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

  6. انقر على الإعدادات واضبط تطبيق Google Chat:

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

أصبح تطبيق Chat جاهزًا لتلقّي الرسائل من خلال Chat والردّ عليها.

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

لاختبار تطبيق Chat، أرسِل رسالة مباشرة إلى التطبيق باتّباع الخطوات التالية:

  1. افتح Google Chat.
  2. لإرسال رسالة مباشرة إلى التطبيق، انقر على بدء محادثة ، وفي النافذة التي تظهر، انقر على البحث عن تطبيقات.
  3. في مربع الحوار البحث عن تطبيقات، ابحث عن Quickstart App.
  4. لفتح رسالة مباشرة باستخدام التطبيق، ابحث عن تطبيق Quickstart وانقر على إضافة > Chat.
  5. في الرسالة المباشرة، اكتب Hello واضغط على enter.

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

تطبيق Chat يستجيب ببطاقة تعرض الاسم المعروض للمُرسِل والصورة الرمزية

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

تحديد الأخطاء وتصحيحها

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