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

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

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

في المخطّط البياني السابق، يتضمّن المستخدم الذي يتفاعل مع تطبيق 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 Cloud:
• تأكَّد من تفعيل الفوترة لمشروعك على 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

   العرض على GitHub

   /**
    * 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

   العرض على GitHub

   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

   العرض على 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.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

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

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

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

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

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

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

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

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

4. اختَر تطبيق Chat من النتائج. وسيتم فتح رسالة مباشرة.

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

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

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

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

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

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

تَنظيم

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

تحذير: يؤدي حذف المشروع إلى ما يلي:

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

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

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

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

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

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

• لإضافة المزيد من الميزات إلى تطبيق Chat، يمكنك الاطّلاع على ما يلي:

  • إنشاء رسائل بطاقات تفاعلية
  • الردّ على الأوامر التي تبدأ بشرطة مائلة
  • فتح مربّعات الحوار والردّ عليها

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