تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الاستمتاع بإجازة باستخدام تطبيق Google Chat

1. مقدمة

توفّر تطبيقات Google Chat الخدمات والموارد مباشرةً في Chat، حيث يمكن للمستخدمين الحصول على المعلومات واتّخاذ الإجراءات بدون مغادرة المحادثة.

في هذا الدرس العملي، ستتعلّم كيفية إنشاء تطبيق Chat، وهو "تطبيق Chat الخاص بالحضور"، الذي يضبط الردود التلقائية في Gmail ويحدّد مواعيد الاجتماعات في "تقويم Google". من خلال إنشاء تطبيق Attendance Chat في Google Apps Script، يمكنك الوصول بسهولة إلى خدمات Google الأخرى، مثل Drive وGmail و"تقويم Google" و"مستندات Google" و"جداول بيانات Google" وغيرها.

أهداف الدورة التعليمية

كيفية إضافة معالِجات في الأحداث التي يتم إنشاؤها في Chat
كيفية تحليل عناصر الأحداث المُرسَلة من Chat
كيفية الردّ على Chat باستخدام ردود منسّقة على شكل بطاقات
كيفية تحديد الإجراءات المخصّصة والاستجابة لها عند النقر على الأزرار في البطاقات

المتطلبات

يجب أن يكون لديك اتصال بالإنترنت ومتصفّح ويب.
حساب Google Workspace لديه إذن الوصول إلى Google Chat
مهارات JavaScript الأساسية: لا تتوافق Google Apps Script إلا مع JavaScript.

2. الحصول على الرمز النموذجي

يمكنك إما تنزيل ملف ZIP أو استنساخ مستودع GitHub للاطّلاع على الرمز البرمجي لكل خطوة في هذا النموذج.

تحتوي مجلدات step-NN ضمن solutions/attendance-chat-app على الحالة النهائية المطلوبة لكل خطوة من خطوات هذا الدرس العملي. وهي متوفّرة للرجوع إليها.

تنزيل الرمز

لتنزيل رمز هذا الدرس العملي، انقر على الزر التالي:

فك حزمة ملف ZIP الذي تم تنزيله. سيؤدي ذلك إلى فك حزمة مجلد جذر (apps-script-samples)، يحتوي على مجلد واحد لكل خطوة من خطوات هذا الدرس العملي ضمن solutions/attendance-chat-app.

استنساخ مستودع GitHub

لاستنساخ مستودع GitHub الخاص بهذا الدرس العملي، شغِّل الأمر التالي:

git clone https://github.com/googleworkspace/apps-script-samples

3- إنشاء معالِجات لأحداث Google Chat

إنشاء مشروع في "برمجة تطبيقات Google"

لإنشاء مشروع Apps Script، اتّبِع الخطوات التالية:

انتقِل إلى script.new.
انقر على مشروع بلا عنوان.
أعِد تسمية النص البرمجي إلى تطبيق "دردشة الحضور" وانقر على إعادة التسمية.

الأحداث في Google Chat

معظم تفاعلات "برمجة تطبيقات Google" مع Chat مستندة إلى الأحداث. عادةً ما يكون التفاعل بين المستخدم وتطبيق Chat وخدمة Chat على النحو التالي:

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

تُنشئ المحادثة 4 أحداث يمكن لتطبيقك الاستماع إليها:

‫ADDED_TO_SPACE: يحدث هذا الحدث عندما يضيف مستخدم بشري تطبيق Chat إلى مساحة أو رسالة مباشرة. في Apps Script، يمكنك تحديد onAddToSpace() دالة للتعامل مع هذا الحدث.
REMOVED_FROM_SPACE: يحدث هذا الحدث عندما يزيل مستخدم تطبيق Chat من مساحة أو رسالة مباشرة. لا ينشر هذا الحدث ردًا في Chat. في Apps Script، يمكنك تحديد onRemoveFromSpace() دالة للتعامل مع هذا الحدث.
‫MESSAGE: يحدث هذا الحدث عندما يرسل مستخدم رسالة إلى تطبيق Chat، إما مباشرةً في رسالة مباشرة أو كإشارة باستخدام @في مساحة. في Apps Script، يمكنك تحديد onMessage() دالة للردّ على هذا الحدث.
‫CARD_CLICKED: يحدث هذا الحدث عندما ينقر المستخدم على زر تم تعيين إجراء مخصّص له. في Apps Script، يمكنك تحديد onCardClick() دالة للردّ على هذا الحدث.

استبدِل محتوى الملف Code.gs بالرمز التالي الذي يحدّد معالِجات للحدثَين ADDED_TO_SPACE وREMOVE_FROM_SPACE. (ستضيف معالجات للحدثَين MESSAGE وCARD_CLICKED لاحقًا في هذا الدرس العملي.)

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. نشر تطبيق Chat واختباره

تعديل ملف بيان النص البرمجي

قبل نشر تطبيقك على Chat، عليك تعديل ملف البيان الخاص بالبرنامج النصي.

انقر على إعدادات المشروع .
ضَع علامة في مربّع الاختيار عرض ملف البيان "appsscript.json" في المحرر.
انقر على أداة التعديل .
انقر على الملف appsscript.json.
أضِف السطر "chat": {} إلى ملف البيان.

يجب أن يبدو ملف البيان مشابهًا للمثال التالي.

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

إنشاء مشروع على Google Cloud

قبل أن تتمكّن من تشغيل تطبيق Chat واختباره، عليك إنشاء مشروع على Google Cloud وتفعيل واجهة Chat API وضبطها ونشر تطبيق Chat في مؤسسة Google Workspace.

في Google Cloud Console، انتقِل إلى "القائمة" > إدارة الهوية وإمكانية الوصول > إنشاء مشروع.
بالنسبة إلى اسم المشروع، أدخِل اسمًا وصفيًا.
إذا طُلب منك ذلك، اختَر المؤسسة وحساب الفوترة.
انقر على إنشاء.
عند اكتمال عملية إنشاء المشروع، سيظهر إشعار في أعلى يسار الصفحة. انقر على الإدخال إنشاء مشروع: <اسم المشروع> لفتح المشروع.
انقر على رمز القائمة > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
انقر على شاشة موافقة OAuth.
في حقل اسم التطبيق، أدخِل تطبيق Attendance Chat.
إذا طُلب منك ذلك، أدخِل عنوان البريد الإلكتروني المخصّص لدعم المستخدمين ومعلومات الاتصال بالمطوّر.
انقر على حفظ ومتابعة.
انقر على "الإعدادات والأدوات" > إعدادات المشروع.
انسخ رقم المشروع.
في محرّر "نصوص برمجية للتطبيقات"، انقر على إعدادات المشروع .
ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
انقر على رقم مشروع GCP وأدخِل رقم المشروع.
انقر على تحديد المشروع.

نشر التطبيق في Chat

لنشر تطبيق Chat على Google Chat، اتّبِع الخطوات التالية:

في محرِّر "برمجة تطبيقات Google"، انقر على نشر > عملية نشر جديدة.
بجانب اختيار النوع، انقر على "تفعيل أنواع النشر" .
اختَر إضافة وانقر على نشر.
انسخ رقم تعريف عملية النشر وانقر على تم.
في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > واجهات برمجة التطبيقات والخدمات > المكتبة.
ابحث عن Google Chat API. اختَر واجهة برمجة التطبيقات من قائمة النتائج.
في صفحة Google Chat API، انقر على تفعيل.
بعد تفعيل واجهة برمجة التطبيقات، انقر على الإعدادات. تجاهل أي رسائل تطلب منك إنشاء بيانات اعتماد.
في صفحة الإعدادات، اتّبِع الخطوات التالية:

أزِل العلامة من المربّع إنشاء تطبيق Chat هذا كإضافة في Workspace، ثم انقر على إيقاف للتأكيد.
في حقل اسم التطبيق، أدخِل تطبيق Attendance Chat.
بالنسبة إلى عنوان URL الخاص بالصورة الرمزية، أدخِل https://goo.gl/kv2ENA.
في حقل الوصف، أدخِل تطبيق Chat في برنامج Apps Script التعليمي.
ضمن الوظائف، اختَر تلقّي رسائل مباشرة.
ضمن إعدادات الربط، اختَر مشروع Apps Script وألصِق رقم تعريف النشر الخاص بالبرنامج النصي في مربّع النص.
ضمن الأذونات، اختَر مستخدمون ومجموعات محدّدة في نطاقك. في مربّع النص أسفل القائمة المنسدلة، أدخِل عنوان بريدك الإلكتروني المرتبط بمؤسستك على Google Workspace.
انقر على حفظ.

بعد حفظ التغييرات، تأكَّد من أنّ الحالة في صفحة Google Chat API تعرض حالة التطبيق على النحو التالي: مباشر - متاح للمستخدمين.

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

لاختبار تطبيقك في Google Chat، اتّبِع الخطوات التالية:

افتح Google Chat.
أرسِل رسالة مباشرة جديدة إلى تطبيق Chat من خلال النقر على "بدء محادثة" > البحث عن تطبيقات.
في صفحة "البحث عن تطبيقات"، ابحث عن تطبيق Attendance Chat.
بجانب تطبيق "دردشة الحضور"، انقر على إضافة > الدردشة.

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

5- تحديد ردّ منسَّق على شكل بطاقة

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

الردود على البطاقات

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

تعرض الصورة التالية استجابة على شكل بطاقة تتضمّن ثلاثة أقسام، بما في ذلك عنوان وقطعة رئيسية/قيمة وقطعة صورة وزر نصي.

للردّ على رسائل المستخدمين ببطاقة، أضِف الرمز التالي إلى ملف Code.gs في تطبيق Chat.

Code.gs

const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
  header: {
    title : 'Attendance Chat app',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  const userMessage = event.message.text;

  const widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

تقرأ الدالة onMessage()، التي تمت إضافتها في هذه الخطوة، رسالة المستخدم الأصلية وتنشئ ردًا كأداة بسيطة من نوع TextParagragh. بعد ذلك، تستدعي الدالة onMessage() الدالة createCardResponse() التي تضع الأداة TextParagraph ضِمن قسم من بطاقة واحدة. يعرض تطبيق Chat عنصر JavaScript الذي تم إنشاؤه باستخدام رد البطاقة مرة أخرى في Google Chat.

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

لاختبار هذا التطبيق، ارجع إلى رسالتك المباشرة مع التطبيق في Google Chat واكتب رسالة (يمكنك كتابة أي رسالة).

يُرجى العِلم أنّ معالج الأحداث onMessage() يحلّل عنصر الحدث الذي يمرّره إليه Google Chat لاستخراج رسالة المستخدم الأصلية. يمكنك أيضًا الحصول على أنواع أخرى من المعلومات حول الحدث، بما في ذلك اسم المستخدم الذي بدأ الحدث وعنوان بريده الإلكتروني واسم المساحة التي وقع فيها الحدث وغير ذلك الكثير.

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

6. التفاعل مع النقرات على الأزرار في البطاقات

في الخطوة السابقة، ردّ تطبيق Chat على رسالة من مستخدم، وهو حدث MESSAGE، ببطاقة بسيطة تحتوي على أداة TextParagragh. في هذه الخطوة، يمكنك إنشاء ردّ يتضمّن أزرارًا، حيث يتضمّن كل زر إجراءً مخصّصًا.

البطاقات التفاعلية

يمكن أن تحتوي ردود البطاقات على أحد نوعَي الأزرار: أدوات أزرار النص التي تعرض أزرارًا نصية فقط، وأدوات ImageButton التي تعرض زرًا يتضمّن رمزًا أو صورة بسيطة بدون نص. يتوافق كلّ من العنصرَين TextButton وImageButton مع أحد السلوكَين onClick (كما هو محدّد في استجابة JSON التي يتم إرسالها إلى Google Chat): إما openLink أو action. كما يوحي الاسم، يفتح openLink رابطًا محدّدًا في علامة تبويب متصفّح جديدة.

يحدّد عنصر action إجراءً مخصّصًا ينفّذه الزر. يمكنك تحديد عدة قيم عشوائية في عنصر الإجراء، بما في ذلك actionMethodName فريد ومجموعة من أزواج المَعلمات الرئيسية / القيمة.

يؤدي تحديد عنصر action للزر إلى إنشاء بطاقة تفاعلية. عندما ينقر المستخدم على الزر في الرسالة، يرسل Google Chat الحدث CARD_CLICKED ويرسل طلبًا إلى التطبيق الذي أرسل الرسالة الأصلية. بعد ذلك، يجب أن يعالج التطبيق الحدث الذي تم إنشاؤه من Google Chat وأن يرسل ردًا إلى المساحة.

استبدِل الدالة onMessage() في Code.gs بالرمز التالي. ينشئ هذا الرمز زرَّين، أحدهما ضبط حالة "خارج المكتب" في Gmail والآخر حظر يوم في "تقويم Google"، في البطاقة التي يتم إرسالها إلى Google Chat.

Code.gs

const REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  const reason = REASON.OTHER;
  const name = event.user.displayName;
  const userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  const widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

للتعامل مع حدث CARD_CLICKED، يجب إضافة الدالة onCardClick() إلى نص برمجة تطبيق Chat. أضِف الرمز التالي الذي يحدّد الدالة onCardClick() Code.gs.

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onCardClick(event) {
  console.info(event);
  let message = '';
  const reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

عند الردّ على نقرات المستخدم، ينفّذ تطبيق Chat أحد الإجراءَين التاليَين: إما أن يضبط الردّ التلقائي أثناء العطلة في Gmail على رسالة "خارج المكتب "، أو أن يجدول اجتماعًا ليوم كامل في"تقويم Google" للمستخدم. لإكمال هذه المهام، يستدعي التطبيق خدمة Gmail المتقدّمة وخدمة "تقويم Google".

أضِف الرمز التالي إلى النص البرمجي لدمج تطبيق Chat مع Gmail و"تقويم Google".

Code.gs

const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  let currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

أخيرًا، يجب تفعيل خدمة Gmail المتقدّمة في المشروع. لتفعيل واجهة برمجة تطبيقات Gmail، اتّبِع الخطوات التالية:

في محرِّر Apps Script، انقر على "إضافة خدمة" بجانب الخدمات.
اختَر Gmail API.
انقر على لوحة بيانات واجهة برمجة التطبيقات في Google Cloud Platform أدناه لفتح Google Cloud Console.
انقر على تفعيل واجهات برمجة التطبيقات والخدمات.
ابحث عن Gmail API وانقر على Gmail API.
في صفحة Gmail API، انقر على تفعيل.

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

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

ملاحظة: إذا طُلب منك منح إذن الوصول إلى التطبيق، قد تحتاج إلى كتابة رسالتك مرة ثانية.

7. تهانينا!

يمكن لتطبيق Chat الآن الردّ على رسائل المستخدمين، وضبط المجيب التلقائي في Gmail، وإضافة حدث لليوم كله في "تقويم Google".

المواضيع التي تناولناها

إنشاء تطبيق Google Chat ونشره باستخدام Apps Script
الردّ على رسائل المستخدمين بردّ بسيط
التفاعل مع خدمات Google Workspace الأخرى نيابةً عن المستخدم من خلال تطبيق Chat

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

1. مقدمة

أهداف الدورة التعليمية

المتطلبات

2. الحصول على الرمز النموذجي

تنزيل الرمز

استنساخ مستودع GitHub

3- إنشاء معالِجات لأحداث Google Chat

إنشاء مشروع في "برمجة تطبيقات Google"

الأحداث في Google Chat

Code.gs

4. نشر تطبيق Chat واختباره

تعديل ملف بيان النص البرمجي

appsscript.json

إنشاء مشروع على Google Cloud

نشر التطبيق في Chat

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

5- تحديد ردّ منسَّق على شكل بطاقة

الردود على البطاقات

Code.gs

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

6. التفاعل مع النقرات على الأزرار في البطاقات

البطاقات التفاعلية

Code.gs

Code.gs

Code.gs

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

7. تهانينا!

المواضيع التي تناولناها

مزيد من المعلومات

الاستمتاع بإجازة باستخدام تطبيق Google Chat