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

توضّح هذه الصفحة كيفية إنشاء إضافة في Google Workspace تعمل في Google Chat باستخدام خدمة HTTP.

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

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

باستخدام بنية HTTP، يمكنك إعداد 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 لنشر الرسائل بشكل غير متزامن أو تنفيذ عمليات أخرى.

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

الأهداف

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

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

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

إعداد البيئة

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

• في Google Cloud Console، فعِّل واجهات برمجة التطبيقات Cloud Build API وCloud Functions API وCloud Pub/Sub API وCloud Logging API وArtifact Registry API وCloud Run API.

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

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

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

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

Node.js

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

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

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

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

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

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

4. في علامة التبويب المصدر:

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

   عرض على GitHub
   import { http } from '@google-cloud/functions-framework';
   
   // The ID of the slash command "/about".
   // You must use the same ID in the Google Chat API configuration.
   const ABOUT_COMMAND_ID = 1;
   
   /**
    * Handle requests from Google Workspace add on
    *
    * @param {Object} req Request sent by Google Chat
    * @param {Object} res Response to be sent back to Google Chat
    */
   http('avatarApp', (req, res) => {
     const chatEvent = req.body.chat;
     let message;
     if (chatEvent.appCommandPayload) {
       message = handleAppCommand(chatEvent);
     } else {
       message = handleMessage(chatEvent);
     }
     res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
       message: message
     }}}});
   });
   
   /**
    * Responds to an APP_COMMAND event in Google Chat.
    *
    * @param {Object} event the event object from Google Chat
    * @return the response message object.
    */
   function handleAppCommand(event) {
     switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
       case ABOUT_COMMAND_ID:
         return {
           text: 'The Avatar app replies to Google Chat messages.'
         };
     }
   }
   
   /**
    * Responds to a MESSAGE event in Google Chat.
    *
    * @param {Object} event the event object from Google Chat
    * @return the response message object.
    */
   function handleMessage(event) {
     // Stores the Google Chat user as a variable.
     const chatUser = event.messagePayload.message.sender;
     const displayName = chatUser.displayName;
     const avatarUrl = chatUser.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 }
           }]}]
         }
       }]
     };
   }

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

Python

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

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

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

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

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

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

4. في علامة التبويب المصدر:

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

   عرض على GitHub
   from typing import Any, Mapping
   
   import flask
   import functions_framework
   
   # The ID of the slash command "/about".
   # You must use the same ID in the Google Chat API configuration.
   ABOUT_COMMAND_ID = 1
   
   @functions_framework.http
   def avatar_app(req: flask.Request) -> Mapping[str, Any]:
     """Handle requests from Google Workspace add on
   
     Args:
       flask.Request req: the request sent by Google Chat
   
     Returns:
       Mapping[str, Any]: the response to be sent back to Google Chat
     """
     chat_event = req.get_json(silent=True)["chat"]
     if chat_event and "appCommandPayload" in chat_event:
       message = handle_app_command(chat_event)
     else:
       message = handle_message(chat_event)
     return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
         "message": message
     }}}}
   
   def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
     """Responds to an APP_COMMAND event in Google Chat.
   
     Args:
       Mapping[str, Any] event: the event object from Google Chat
   
     Returns:
       Mapping[str, Any]: the response message object.
     """
     if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
       return {
         "text": "The Avatar app replies to Google Chat messages.",
       }
     return {}
   
   def handle_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
     """Responds to a MESSAGE event in Google Chat.
   
     Args:
       Mapping[str, Any] event: the event object from Google Chat
   
     Returns:
       Mapping[str, Any]: the response message object.
     """
     # Stores the Google Chat user as a variable.
     chat_user = event["messagePayload"]["message"]["sender"]
     display_name = chat_user.get("displayName", "")
     avatar_url = chat_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 }},
           ]}]
         }
       }]
     }

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

جافا

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

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

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

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

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

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

4. في علامة التبويب المصدر:

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

   عرض على GitHub
   package com.google.chat.avatar;
   
   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 App implements HttpFunction {
     // The ID of the slash command "/about".
     // You must use the same ID in the Google Chat API configuration.
     private static final int ABOUT_COMMAND_ID = 1;
   
     private static final Gson gson = new Gson();
   
     /**
      * Handle requests from Google Workspace add on
      * 
      * @param request the request sent by Google Chat
      * @param response the response to be sent back to Google Chat
      */
     @Override
     public void service(HttpRequest request, HttpResponse response) throws Exception {
       JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
       JsonObject chatEvent = event.getAsJsonObject("chat");
       Message message;
       if (chatEvent.has("appCommandPayload")) {
         message = handleAppCommand(chatEvent);
       } else {
         message = handleMessage(chatEvent);
       }
       JsonObject createMessageAction = new JsonObject();
       createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
       JsonObject chatDataAction = new JsonObject();
       chatDataAction.add("createMessageAction", createMessageAction);
       JsonObject hostAppDataAction = new JsonObject();
       hostAppDataAction.add("chatDataAction", chatDataAction);
       JsonObject dataActions = new JsonObject();
       dataActions.add("hostAppDataAction", hostAppDataAction);
       response.getWriter().write(gson.toJson(dataActions));
     }
   
     /**
      * Handles an APP_COMMAND event in Google Chat.
      *
      * @param event the event object from Google Chat
      * @return the response message object.
      */
     private Message handleAppCommand(JsonObject event) throws Exception {
       switch (event.getAsJsonObject("appCommandPayload")
         .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
         case ABOUT_COMMAND_ID:
           return new Message()
             .setText("The Avatar app replies to Google Chat messages.");
         default:
           return null;
       }
     }
   
     /**
      * Handles a MESSAGE event in Google Chat.
      *
      * @param event the event object from Google Chat
      * @return the response message object.
      */
     private Message handleMessage(JsonObject event) throws Exception {
       // Stores the Google Chat user as a variable.
       JsonObject chatUser = event.getAsJsonObject("messagePayload").getAsJsonObject("message").getAsJsonObject("sender");
       String displayName = chatUser.has("displayName") ? chatUser.get("displayName").getAsString() : "";
       String avatarUrl = chatUser.has("avatarUrl") ? chatUser.get("avatarUrl").getAsString() : "";
       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)))))))));
     }
   }

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

   java/chat/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>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.1.4</version>
       </dependency>
       <dependency>
         <groupId>com.google.code.gson</groupId>
         <artifactId>gson</artifactId>
         <version>2.9.1</version>
       </dependency>
       <dependency>
         <groupId>com.google.apis</groupId>
         <artifactId>google-api-services-chat</artifactId>
         <version>v1-rev20230115-2.0.0</version>
       </dependency>
     </dependencies>
   
     <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>

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

يتم فتح صفحة تفاصيل خدمة Cloud Run. انتظِر إلى أن يتم نشر الدالة.

ضبط الإضافة

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

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

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

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

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

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

4. في حقل البحث في Google Cloud، ابحث عن "Google Chat API"، ثم انقر على Google Chat API، ثم على إدارة.

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

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

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

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

بعد ذلك، امنح تطبيق Chat الإذن باستدعاء وظيفة Cloud Run.

منح Google Chat الإذن بتنفيذ وظيفتك

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

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

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

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

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

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

5. في المستخدمون الرئيسيون الجدد، أدخِل عنوان البريد الإلكتروني لحساب الخدمة الخاص بإضافة Google Workspace المرتبط بتطبيق Chat.

   يمكنك العثور على عنوان البريد الإلكتروني لحساب الخدمة في صفحة إعدادات Chat API، ضمن إعدادات الاتصال > عنوان URL لنقطة نهاية HTTP > البريد الإلكتروني لحساب الخدمة:

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

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

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

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

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

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

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

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

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

4. اختَر تطبيق 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 مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بحذف مشروع Cloud.

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

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

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

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

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

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