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

توضّح هذه الصفحة كيفية إنشاء تطبيق HTTP في Chat. هناك طرق مختلفة لتنفيذ هذه البنية. في Google Cloud، يمكنك استخدام دوال Cloud وCloud Run وApp Engine. في هذه البداية السريعة، كتابة ونشر الوظائف السحابية التي يستخدمها تطبيق 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 APIs، يجب تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيقات واحدة أو أكثر في مشروع واحد على Google Cloud.
  • في وحدة التحكّم في Google Cloud، فعِّل واجهة برمجة التطبيقات Google Chat وCloud Build API وCloud Functions API واجهة برمجة تطبيقات Cloud Pub/Sub وCloud Logging API وواجهة برمجة تطبيقات Artifact Registry وCloud Run API

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

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

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

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

Node.js

  1. في وحدة التحكّم في Google Cloud، انتقِل إلى صفحة "وظائف السحابة الإلكترونية":

    الانتقال إلى وظائف السحابة الإلكترونية

    تأكَّد من أنّ مشروع تطبيق Chat: المحددة.

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

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

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

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

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

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

    node/avatar-app/index.js
    // The ID of the slash command "/about".
    // It's not enabled by default, set to the actual ID to enable it. You need to
    // use the same ID as set in the Google Chat API configuration.
    const ABOUT_COMMAND_ID = "";
    
    /**
     * 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.message) {
        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 event = req.body;
    
      // Checks for the presence of a slash command in the message.
      if (event.message.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (event.message.slashCommand.commandId) {
          case ABOUT_COMMAND_ID:
            return res.send({
              privateMessageViewer: event.user,
              text: 'The Avatar app replies to Google Chat messages.'
            });
        }
      }
    
      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} avatarUrl the URL for the sender's avatar
     * @return {Object} a card with the user's avatar.
     */
    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 }
            }]}]
          }
        }]
      };
    }

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

Python

  1. في وحدة التحكّم في Google Cloud، انتقِل إلى صفحة "وظائف السحابة الإلكترونية":

    الانتقال إلى وظائف السحابة الإلكترونية

    تأكَّد من أنّ مشروع تطبيق Chat: المحددة.

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

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

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

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

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

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

    python/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # The ID of the slash command "/about".
    # It's not enabled by default, set to the actual ID to enable it. You need to
    # use the same ID as set in the Google Chat API configuration.
    ABOUT_COMMAND_ID = ""
    
    @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)
    
      # Checks for the presence of a slash command in the message.
      if "slashCommand" in request_json["message"]:
        # Executes the slash command logic based on its ID.
        # Slash command IDs are set in the Google Chat API configuration.
        if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
          return {
            "privateMessageViewer": request_json["user"],
            "text": 'The Avatar app replies to Google Chat messages.'
          }
    
      display_name = request_json["message"]["sender"]["displayName"]
      avatar = request_json["message"]["sender"]["avatarUrl"]
      response = create_message(name=display_name, image_url=avatar)
      return response
    
    
    def create_message(name: str, image_url: str) -> Mapping[str, Any]:
      """Google Cloud Function that handles requests from Google Chat
    
      Args:
          str name: the sender's display name.
          str image_url: the URL for the sender's avatar.
    
      Returns:
          Mapping[str, Any]: a card with the user's avatar.
      """
      return {
        "text": "Here's your avatar",
        "cardsV2": [{
          "cardId": "avatarCard",
          "card": {
              "name": "Avatar Card",
              "header": { "title": f"Hello {name}!" },
              "sections": [{
                "widgets": [{
                  "textParagraph": { "text": "Your avatar picture:" }
                }, {
                  "image": { "imageUrl": image_url }
                }]
              }]
          }
        }]
      }

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

Java

  1. في وحدة التحكّم في Google Cloud، انتقِل إلى صفحة "وظائف السحابة الإلكترونية":

    الانتقال إلى وظائف السحابة الإلكترونية

    تأكَّد من أنّ مشروع تطبيق Chat: المحددة.

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

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

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

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

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

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

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

    java/avatar-app/src/main/java/App.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 App implements HttpFunction {
      private static final Gson gson = new Gson();
    
      // The ID of the slash command "/about".
      // It's not enabled by default, set to the actual ID to enable it. You need to
      // use the same ID as set in the Google Chat API configuration.
      private static final String ABOUT_COMMAND_ID = "";
    
      @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;
        }
    
        // Checks for the presence of a slash command in the message.
        if (body.getAsJsonObject("message").has("slashCommand")) {
          // Executes the slash command logic based on its ID.
          // Slash command IDs are set in the Google Chat API configuration.
          JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
          switch (slashCommand.get("commandId").getAsString()) {
            case ABOUT_COMMAND_ID:
            JsonObject aboutMessage = new JsonObject();
            aboutMessage.addProperty("text", "The Avatar app replies to Google Chat messages.");
            aboutMessage.add("privateMessageViewer", body.getAsJsonObject("user"));
              response.getWriter().write(gson.toJson(aboutMessage));
              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>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.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 باستدعاء الوظيفة، أضِف تطبيق Google Chat حساب خدمة يكون له دور Cloud Run Invoker.

  1. في Google Cloud Console، انتقِل إلى صفحة "تشغيل السحابة الإلكترونية":

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

  2. في قائمة خدمات تشغيل السحابة الإلكترونية، حدد مربع الاختيار بجوار مربع الأخرى. (لا تنقر على الدالة نفسها.)

  3. انقر على الأذونات. ستظهَر لوحة الأذونات.

  4. انقر على إضافة مدير.

  5. في العناصر الرئيسية الجديدة، أدخِل chat@system.gserviceaccount.com.

  6. في اختيار دور، اختَر تشغيل في السحابة الإلكترونية > Cloud Run Invoker

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

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

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

  1. في وحدة تحكُّم Google Cloud، انقر على "القائمة" &gt; وظائف السحابة الإلكترونية.

    الانتقال إلى وظائف السحابة الإلكترونية

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

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

  3. انقر على علامة التبويب العوامل المشغِّلة.

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

تطبيق Chat جاهز للاستلام والردّ على الرسائل على 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 أو تعرض card خطأً، تعرض واجهة Chat رسالة مفادها "حدث خطأ". أو "تعذَّرت معالجة طلبك". في بعض الأحيان، لا يمكن واجهة مستخدم Chat لا يعرض أي رسالة خطأ، ولكن يظهر تطبيق Chat أو ينتج عن بطاقة نتيجة غير متوقعة؛ على سبيل المثال، قد لا تظهر رسالة البطاقة موضع الإعلان.

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

تَنظيم

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

  1. في وحدة تحكُّم Google Cloud، انتقِل إلى صفحة إدارة الموارد. (يُرجى النقر.) قائمة الطعام &gt; إدارة الهوية وإمكانية الوصول و المشرف &gt; إدارة الموارد.

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

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