كائنات الأحداث

توضّح هذه الصفحة بنية عناصر أحداث إضافات Google Workspace.

عناصر الأحداث هي بنى JSON يتم إنشاؤها تلقائيًا وتمريرها كمَعلمات لتشغيل وظائف الاستدعاء أو استدعاؤها عندما يتفاعل مستخدم مع إحدى الإضافات. تحمل عناصر الأحداث معلومات من جهة العميل عن التطبيق المضيف والسياق الحالي إلى وظيفة الاستدعاء من جهة الخادم في الإضافة.

تستخدم إضافات Google Workspace عناصر الأحداث في المواضع التالية:

• مشغّلات الصفحة الرئيسية: يتم تلقائيًا تمرير عنصر حدث إلى كلّ وظيفة homepageTrigger تحدّدها عند بدء وظيفة مشغّل الصفحة الرئيسية. يمكنك استخدام هذا العنصر في دالة تشغيل الصفحة الرئيسية لتحديد التطبيق المضيف النشط والمنصة للعميل ولغة المستخدم ومعلومات أخرى.

  لا تحتوي عناصر الأحداث التي يتم إنشاؤها عند بدء تنشيط الصفحة الرئيسية على كل الحقول المضمّنة في الحالتَين الأخرتَين، ويتم حذف الحقول المتعلّقة بالتطبيقات المصغّرة و المعلومات السياقية.

• العوامل المشغِّلة السياقية: يقدّم كل تطبيق مضيف مجموعة مختلفة من عوامل التفعيل السياقية التي يتم تفعيلها عندما يدخل المستخدم سياقًا معيّنًا. على سبيل المثال:

  • يقدّم Gmail عامل تشغيل سياقيًا عندما يفتح مستخدم رسالة وعامل تشغيل آخر عندما ينشئ مستخدم رسالة.
  • يقدّم "تقويم Google" عامل تشغيل سياقيًا عندما يفتح أحد المستخدِمينحدثًا.
  • يوفّر Google Drive عامل تشغيل سياقيًا عندما يختار أحد المستخدِمين ملفات Drive.

  عند بدء تشغيل عامل تشغيل سياقي، يستدعي التطبيق المضيفrunFunctionالمقابل المدرَج في بيان الملحق، ويمرّر إليه كائن حدث كوسيطة. إنّ عناصر الأحداث التي يتم إنشاؤها عند بدء عوامل التفعيل السياقية تحتوي على جميع الحقول المضمّنة في عناصر حدث التفعيل في الصفحة الرئيسية ، بالإضافة إلى الحقول التي تحتوي على معلومات سياقية.

• إجراءات التطبيقات المصغّرة تُستخدَم عناصر الأحداث أيضًا لتوفير تفاعل أداة مصغّرة ، باستخدام نموذج الإجراءات نفسه الذي تستخدمه إضافات Gmail. تستخدِم إضافات Google Workspace جميع وظائف معالِج التطبيقات المصغّرة والعناصر Action والاستجابات للإجراءات نفسها. في المقابل، في إضافات Google Workspace، تتضمن عناصر أحداث الإجراءات مزيدًا من المعلومات التي يمكن لوظيفة الاستدعاء الردّ عليها.

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

• عوامل تشغيل معاينة الرابط في "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google"، يمكنك ضبط معاينات الروابط للخدمات التابعة لجهات خارجية استنادًا إلى أنماط عناوين URL معيّنة. عندما يتفاعل المستخدمون مع رابط يستوفي النمط، يتم تنشيط الحدث linkPreviewTriggers ويتم تمرير كائن الحدث الذي يحتوي على الرابط إلى دالة callback الخاصة بالعامل المشغِّل. يمكن أن تستخدم الإضافة عنصر الحدث هذا لإنشاء شريحة ذكية وبطاقة تعرض معلومات عن الرابط ضمن التطبيق المضيف. يمكنك أيضًا إنشاء إجراءات تطبيقات مصغّرة للسماح للمستخدمين بالتفاعل مع بطاقة المعاينة ومحتوياتها.

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

بنية عنصر الحدث

يوضّح الجدول التالي بنية المستوى الأعلى لعناصر أحداث تطبيقات إضافات Google Workspace. تتضمّن بنية حدث العنصر حقل commonEventObject أعلى مستوى للمعلومات غير المستندة إلى المضيف. يمكن أن يحتوي كل عنصر حدث أيضًا على أحد حقول المستوى الأعلى التالية الخاصة بالمضيف، والتي يحدّدها التطبيق المضيف النشط: gmailEventObject أو calendarEventObject أو driveEventObject.

للحفاظ على التوافق مع الإصدارات القديمة، تتضمّن ملفّات تعريف أحداث إضافات Google Workspace أيضًا جميع الحقول الأصلية المستخدَمة في ملفّات تعريف أحداث إجراءات إضافات Gmail. تم إدراج هذه الحقول في الجدول أدناه ضمن "حقول الإضافة الأصلية في Gmail"، ويُرجى العِلم أنّه تتم إعادة إنتاج المعلومات الواردة في هذه الحقول في بنية العنصر الجديدة.

عنصر الحدث الشائع

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

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

مدخلات نموذج أداة اختيار التاريخ والوقت

دالّات ردّ الاتصال بالإجراءات يمكنها تلقّي قيم التطبيقات المصغّرة الحالية في الحقل commonEventObject.formInputs. ويشمل ذلك قيم التاريخ أو الوقت التي اختارها المستخدم في تطبيقات مصغرة لاختيار التاريخ أو الوقت. ومع ذلك، تختلف بنية المعلومات حسب ما إذا تم ضبط القطعة كأداة اختيار للتاريخ والوقت أو أداة اختيار للتاريخ فقط أو أداة اختيار للوقت فقط. في الجدول التالي، يمكنك الاطّلاع على الاختلافات الهيكلية:

عنصر حدث التقويم

عنصر حدث التقويم هو الجزء من عنصر الحدث العام الذي يحمل معلومات عن تقويم المستخدم وأحداث التقويم. ولا يظهر سوى في عنصر حدث إذا كان التطبيق المضيف هو "تقويم Google".

يسرد الجدول التالي الحقول المتوفّرة في حقل calendarEventObject لعنصر الحدث. تكون الحقول التي تم وضع علامة عليها على أنّها بيانات أنشأها المستخدم متوفّرة في عنصر الحدث إذا كانت البيانات متوفرة في حدث "تقويم Google" فقط وكانت الإضافة تضبط حقل addOns.calendar.currentEventAccess manifest على READ أو READ_WRITE.

الضيف

تحتوي عناصر "الضيوف" على معلومات عن الضيوف الفرديين في أحداث "تقويم Google". تظهر هذه المعلومات في عنصر الحدث إذا كانت البيانات متوفّرة في حدث "تقويم Google" وكانت الإضافة تضبط حقل addOns.calendar.currentEventAccess manifest على READ أو READ_WRITE.

بيانات المؤتمر

تحتوي عناصر بيانات مكالمات الفيديو على معلومات عن مكالمات الفيديو المرفقة بأحداث "تقويم Google". يمكن أن تكون هذه الحلول تابعة لشركة Google، مثل Google Meet، أو حلول تابعة لجهات خارجية. تتوفّر هذه المعلومات في ملف تعريف الحدث إذا كانت البيانات متوفّرة في حدث "تقويم Google" فقط، وضبطت الإضافة حقل addOns.calendar.currentEventAccess manifest على READ أو READ_WRITE.

نقطة الإدخال

تحتوي عناصر نقاط الدخول على معلومات عن وسائل الوصول المعتمَدة إلى اجتماع معيّن، مثل الهاتف أو الفيديو. تظهر هذه المعلومات في عنصر الحدث إذا كانت البيانات متوفّرة في حدث "تقويم Google" فقط، وصنّفت الإضافة حقل addOns.calendar.currentEventAccess manifest على READ أو READ_WRITE.

عنصر حدث Drive

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

ملف في Drive

تحتوي عناصر عناصر Drive على معلومات عن عناصر Drive معيّنة، مثل الملفات أو المجلدات.

عنصر حدث Gmail

عنصر حدث Gmail هو الجزء من عنصر الحدث العام الذي يحمل معلومات عن رسائل Gmail الخاصة بالمستخدم. ولا يظهر هذا الحقل إلا في عنصر حدث إذا كان التطبيق المضيف هو Gmail.

عنصر حدث "مستندات Google"

عنصر حدث "مستندات Google" هو الجزء من عنصر الحدث العام الذي يحمل معلومات عن مستند المستخدم ومحتوياته. ولا يظهر هذا العنصر إلا في عنصر الحدث إذا كان التطبيق المضيف هو "مستندات Google".

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

عنصر حدث "جداول بيانات Google"

عنصر حدث "جداول بيانات Google" هو الجزء من عنصر الحدث العام الذي يحمل معلومات عن مستند المستخدم ومحتوياته. ولا يظهر هذا العنصر إلا في ملف حدث إذا كان التطبيق المضيف هو "جداول بيانات Google".

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

عنصر حدث "العروض التقديمية من Google"

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

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}