إنشاء تطبيق Google Chat باستخدام Google Cloud Functions

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

الأهداف

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

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

إعداد البيئة

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

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

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

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

Node.js

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

    الانتقال إلى صفحة "دوال السحابة"

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

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

  3. في صفحة إنشاء الدالة، أعدّ دالتك:

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

      لمزيد من المعلومات عن المصادقة في Google Workspace، يُرجى الاطّلاع على مصادقة تطبيقات Chat وطلبات واجهة برمجة التطبيقات واعتمادهما.

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

    5. انقر على التالي.

  4. في وقت التشغيل، اختر Node.js 10.

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

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

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

    /**
      * 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.
      */
    exports.helloChat = function helloChat(req, res) {
      if (req.method === 'GET' || !req.body.message) {
        res.send('Hello! This function must be called from Google Chat.');
      }
    
      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': imageURL},
      };
    
      const avatarSection = {
        'widgets': [
          avatarWidget,
          avatarImageWidget,
        ],
      };
    
      return {
        'cards': [{
          'name': 'Avatar Card',
          'header': cardHeader,
          'sections': [avatarSection],
        }],
      };
    }
    
  8. انقر على نشر.

لغة Python

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

    الانتقال إلى صفحة "دوال السحابة"

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

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

  3. في صفحة إنشاء الدالة، أعدّ دالتك:

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

      لمزيد من المعلومات عن المصادقة في Google Workspace، يُرجى الاطّلاع على مصادقة تطبيقات Chat وطلبات واجهة برمجة التطبيقات واعتمادهما.

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

    5. انقر على التالي.

  4. في Runtime، اختَر Python 3.10.

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

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

  7. استبدل محتوى 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):
      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 = {'cards': [{'name': 'Avatar Card',
                          'header': header, 'sections': [avatar_section]}]}
    
      return cards
    
  8. انقر على نشر.

لغة Java

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

    الانتقال إلى صفحة "دوال السحابة"

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

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

  3. في صفحة إنشاء الدالة، أعدّ دالتك:

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

      لمزيد من المعلومات عن المصادقة في Google Workspace، يُرجى الاطّلاع على مصادقة تطبيقات Chat وطلبات واجهة برمجة التطبيقات واعتمادهما.

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

    5. انقر على التالي.

  4. في Runtime، اختَر Java 11.

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

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

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

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

    java/avatar-bot/src/main/java/HelloChat.java
    import com.google.api.services.chat.v1.model.Card;
    import com.google.api.services.chat.v1.model.CardHeader;
    import com.google.api.services.chat.v1.model.Image;
    import com.google.api.services.chat.v1.model.Message;
    import com.google.api.services.chat.v1.model.Section;
    import com.google.api.services.chat.v1.model.TextParagraph;
    import com.google.api.services.chat.v1.model.WidgetMarkup;
    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) {
        CardHeader cardHeader = new CardHeader().setTitle(String.format("Hello %s!", displayName));
        TextParagraph textParagraph = new TextParagraph().setText("Your avatar picture: ");
        WidgetMarkup avatarWidget = new WidgetMarkup().setTextParagraph(textParagraph);
        Image image = new Image().setImageUrl(avatarUrl);
        WidgetMarkup avatarImageWidget = new WidgetMarkup().setImage(image);
        Section section = new Section().setWidgets(List.of(avatarWidget, avatarImageWidget));
        Card card = new Card().setName("Avatar Card").setHeader(cardHeader).setSections(List.of(section));
    
        return new Message().setCards(List.of(card));
      }
    }

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

    java/avatar-bot/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-rev135-1.25.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 Functions له.

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

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

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

  5. ابحث عن "Google Chat API" وانقر على Google Chat API.

  6. انقر على إدارة.

  7. انقر على ضبط وإعداد تطبيق 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. ضمن الأذونات، اختَر أشخاص ومجموعات محدّدة في نطاقك وأدخِل عنوان البريد الإلكتروني.
  8. انقر على حفظ.

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

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

لاختبار تطبيق Chat، أرسل رسالة مباشرة إليه:

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

يعرض التطبيق بطاقة تتضمّن اسم العرض والصورة الرمزية.

الخطوات التالية

لتحديد مشاكل تطبيق Chat وحلّها فيه، يُرجى الرجوع إلى هذه الصفحات:

  • أثناء إنشاء تطبيق Chat، قد تحتاج إلى تصحيح الأخطاء فيه من خلال قراءة سجلات أخطاء التطبيق. لقراءة السجلّات، في وحدة تحكُّم Google Cloud، انتقِل إلى مستكشف السجلات.
  • تحرّي الخلل وإصلاحه.

لإضافة المزيد من الوظائف إلى تطبيق Chat، ارجع إلى الأدلة التالية:

  • إنشاء بطاقات تفاعلية — تدعم رسائل البطاقات تنسيقًا محددًا وعناصر واجهة مستخدم تفاعلية مثل الأزرار والوسائط الغنية مثل الصور. استخدم رسائل البطاقات لتقديم معلومات مفصلة، وجمع المعلومات من المستخدمين، وأرشد المستخدمين لاتخاذ الخطوة التالية.
  • أوامر الشرطة المائلة للدعم - تتيح لك الأوامر التي تبدأ بشرطة مائلة تسجيل أوامر محدّدة يمكن أن يمنحها تطبيقك لتطبيقك والإعلان عنها من خلال كتابة أمر يبدأ بشرطة مائلة للأمام (/)، مثل /help.
  • مربعات حوار التشغيل — مربعات الحوار هي نوافذ تستند إلى بطاقات ويمكن أن يفتحها تطبيقك للتفاعل مع المستخدم. يمكن ربط بطاقات متعددة معًا بالتسلسل، ما يساعد المستخدمين على إكمال العمليات متعددة الخطوات، مثل ملء بيانات النموذج.

للاطّلاع على المزيد من المعلومات حول Google Chat API، يمكنك الاطّلاع على المستندات المرجعية.