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

توضّح هذه الصفحة بنية عناصر أحداث إضافات 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"، ويُرجى العِلم أنّه تتم إعادة إنتاج المعلومات الواردة في هذه الحقول في بنية العنصر الجديدة.

عنصر الحدث
eventObject.commonEventObject Common fields object
عنصر يحتوي على معلومات مشتركة بين جميع عناصر الأحداث، بغض النظر عن التطبيق المضيف.
eventObject.calendar Calendar event object
لا يظهر هذا الحقل إلّا إذا كان المضيف المتصل هو "تقويم Google". عنصر يحتوي على معلومات التقويم والأحداث
eventObject.chat Chat event object
لا يظهر هذا الحقل إلا إذا كان المضيف المتصل هو Google Chat. عنصر يحتوي على معلومات Chat
eventObject.drive Drive event object
لا يظهر هذا الحقل إلا إذا كان المضيف المُتصل هو Google Drive. عنصر يحتوي على معلومات Drive
eventObject.gmail Gmail event object
لا يظهر هذا الحقل إلّا إذا كان المضيف المتصل هو Gmail. عنصر يحتوي على معلومات Gmail
eventObject.docs Docs event object
لا يظهر هذا الحقل إلا إذا كان المضيف المُتصل هو "مستندات Google". عنصر يحتوي على معلومات عن "مستندات Google"
eventObject.sheets Sheets event object
لا يظهر هذا الحقل إلّا إذا كان المضيف المتصل هو "جداول بيانات Google". عنصر يحتوي على معلومات "جداول بيانات Google"
eventObject.slides Slides event object
لا يظهر هذا الخيار إلا إذا كان المضيف المتصل هو "العروض التقديمية من Google". عنصر يحتوي على معلومات "العروض التقديمية من Google"
حقول إضافات Gmail الأصلية
eventObject.messageMetadata.accessToken string
تمّ إيقاف هذا العمود نهائيًا. رمز دخول يمكنك استخدام هذا الإجراء لتفعيل الوصول إلى بيانات المستخدمين باستخدام نطاقات إضافات Gmail المؤقتة.

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.gmail.accessToken.

eventObject.messageMetadata.messageId string
تمّ إيقاف هذا العمود نهائيًا. رقم تعريف الرسالة لسلسلة المحادثات في واجهة مستخدم Gmail

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.gmail.messageId.

eventObject.clientPlatform string
تمّ إيقاف هذا العمود نهائيًا. يشير إلى مصدر الحدث (الويب أو iOS أو Android).

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.commonEventObject.platform.

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

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في حقل eventObject.commonEventObject.formInputs بدلاً من ذلك. ويتم تمثيل التطبيقات المصغّرة التي تحتوي على قيم فردية كصفائف تحتوي على عنصر واحد.

eventObject.formInputs object
تمّ إيقاف هذا العمود نهائيًا. خريطة للقيم الحالية للتطبيقات المصغّرة في البطاقة، يتم عرضها كقوائم من السلاسل. المفاتيح هي معرّفات السلاسل المرتبطة بالتطبيق المصغّر. بالنسبة إلى التطبيقات المصغّرة ذات القيمة الواحدة، يتم عرض قيمة في صفيف يتضمّن عنصرًا واحدًا. بالنسبة إلى التطبيقات المصغّرة التي تتضمّن قيمًا متعددة، مثل مجموعات مربّعات الاختيار، يتم عرض جميع القيم في قائمة.

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.commonEventObject.formInputs.

eventObject.parameters object
تمّ إيقاف هذا العمود نهائيًا. خريطة لأي مَعلمات إضافية يتم تقديمها إلى Action باستخدام Action.setParameters() مفاتيح الخريطة وقيمها هي سلاسل.

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.commonEventObject.parameters.

eventObject.userCountry string
تم إيقافها نهائيًا وغير مفعّلة تلقائيًا. رمز مكوّن من حرفَين يشير إلى بلد أو منطقة المستخدم ويمكن أن يكون أيضًا رمز بلد UN M49 رقميًا.

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.commonEventObject.userLocale.

eventObject.userLocale string
تم إيقافها نهائيًا وغير مفعّلة تلقائيًا. رمز ISO 639 المكوّن من حرفَين ويشير إلى لغة المستخدم اطّلِع على الوصول إلى لغة المستخدم والمنطقة الزمنية للحصول على مزيد من التفاصيل.

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.commonEventObject.userLocale.

eventObject.userTimezone.id string
تم إيقافها نهائيًا وغير مفعّلة تلقائيًا. معرّف المنطقة الزمنية لمنطقة المستخدم الزمنية على سبيل المثال: America/New_York وEurope/Vienna وAsia/Seoul. اطّلِع على الوصول إلى لغة المستخدم والمنطقة الزمنية للحصول على مزيد من التفاصيل.

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.commonEventObject.timeZone.id.

eventObject.userTimezone.offset string
تم إيقافها نهائيًا وغير مفعّلة تلقائيًا. الاختلاف الزمني عن التوقيت العالمي المنسق (UTC) لمنطقة المستخدم الزمنية، تقاس بالملي ثانية اطّلِع على الوصول إلى لغة المستخدم والمنطقة الزمنية للحصول على مزيد من التفاصيل.

بالنسبة إلى إضافات Google Workspace، يمكنك العثور على هذه المعلومات في الحقل eventObject.commonEventObject.timeZone.offset.

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

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

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

الحقول الشائعة لكائنات الأحداث
commonEventObject.platform string
يشير إلى مصدر الحدث ("الويب" أو "iOS" أو "Android").
commonEventObject.formInputs object
خريطة تحتوي على القيم الحالية للتطبيقات المصغّرة في البطاقة المعروضة مفاتيح الخريطة هي معرّفات السلاسل التي تمّ تعيينها لكلّ تطبيق مصغّر.

تعتمد بنية عنصر قيمة الخريطة على نوع التطبيق المصغّر:

  • التطبيقات المصغّرة ذات القيمة الواحدة (مثل مربّع نص): قائمة بسلاسل ملفوظة (عنصر واحد فقط)

    مثال: بالنسبة إلى التطبيق المصغّر لإدخال نص يحمل الرقم التعريفي employeeName، يمكنك الوصول إلى قيمة إدخال النص باستخدام: e.commonEventObject.formInputs.employeeName.stringInputs.value[0]

  • التطبيقات المصغّرة التي تتضمّن قيمًا متعددة (مثل مجموعات مربّعات الاختيار): قائمة بسلسلتَين

    مثال: بالنسبة إلى التطبيق المصغّر المتعدّد القيم الذي يستخدم participants كرقمه التعريفي، يمكنك الوصول إلى صفيف القيمة باستخدام: e.commonEventObject.formInputs.participants.stringInputs.value.

  • A date-time picker: a DateTimeInput object.

    مثال: بالنسبة إلى أداة اختيار لها رقم تعريف myDTPicker، يمكنك الوصول إلى كائن DateTimeInput باستخدام e.commonEventObject.formInputs.myDTPicker.dateTimeInput.

  • A date-only picker: a DateInput object.

    مثال: بالنسبة إلى أداة اختيار لها رقم تعريف myDatePicker، يمكنك الوصول إلى كائن DateInput باستخدام e.commonEventObject.formInputs.myDatePicker.dateInput.

  • A time-only picker: a TimeInput object.

    مثال: بالنسبة إلى أداة اختيار لها رقم تعريف myTimePicker، يمكنك الوصول إلى كائن TimeInput باستخدام e.commonEventObject.formInputs.myTimePicker.timeInput.
commonEventObject.hostApp string
يشير إلى التطبيق المضيف الذي تكون الإضافة نشطة فيه عند إنشاء عنصر الحدث. تشمل القيم المحتمَلة ما يلي:
  • GMAIL
  • CALENDAR
  • DRIVE
  • DOCS
  • SHEETS
  • SLIDES
commonEventObject.parameters object
أي مَعلمات إضافية تُقدّمها إلى إجراء باستخدام actionParameters أو Action.setParameters().

الإصدار التجريبي للمطوّرين: بالنسبة إلى الإضافات التي توفّر ميزات إضافية في Google Chat، لاقتراح عناصر استنادًا إلى ما يطلبه المستخدمون في قوائم الاختيار المتعدّد، استخدِم قيمة مفتاح "autocomplete_widget_query" (event.commonEventObject.parameters["autocomplete_widget_query"]). يمكنك استخدام هذه القيمة لطلب بيانات من قاعدة بيانات واقتراح عناصر قابلة للاختيار للمستخدمين أثناء كتابتهم. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة جمع المعلومات من مستخدمي Google Chat ومعالجتها.
commonEventObject.userLocale string
غير مفعَّل تلقائيًا. لغة المستخدِم ومعرّف البلد/المنطقة بتنسيق رمز اللغة ISO 639 رمز البلد/المنطقة ISO 3166 على سبيل المثال، en-US.

لتفعيل هذا الحقل، يجب ضبط addOns.common.useLocaleFromApp على true في ملف بيان الإضافة. يجب أن تتضمّن أيضًا قائمة نطاق الإضافة العنصر https://www.googleapis.com/auth/script.locale. اطّلِع على الوصول إلى لغة المستخدم والمنطقة الزمنية للحصول على مزيد من التفاصيل.

commonEventObject.timeZone string
غير مفعَّل تلقائيًا. معرّف المنطقة الزمنية ومعاملتها لتفعيل هذا الحقل، يجب ضبط قيمة addOns.common.useLocaleFromApp على true في ملف بيان الإضافة. يجب أن تتضمّن أيضًا قائمة نطاق الإضافة https://www.googleapis.com/auth/script.locale. اطّلِع على الوصول إلى لغة المستخدم والمنطقة الزمنية للحصول على مزيد من التفاصيل.
commonEventObject.timeZone.id string
معرّف المنطقة الزمنية لمنطقة المستخدم الزمنية. تشمل الأمثلة على ذلك: America/New_York وEurope/Vienna Asia/Seoul. لتفعيل هذا الحقل، يجب ضبط قيمة addOns.common.useLocaleFromApp على true في ملف بيان الإضافة. يجب أن تتضمّن أيضًا قائمة نطاق الإضافة https://www.googleapis.com/auth/script.locale. اطّلِع على الوصول إلى لغة المستخدم والمنطقة الزمنية للحصول على مزيد من التفاصيل.
commonEventObject.timeZone.offset string
الاختلاف الزمني بالملي ثانية بين المنطقة الزمنية للمستخدِم و التوقيت العالمي المنسق (UTC) اطّلِع على الوصول إلى لغة المستخدم والمنطقة الزمنية للحصول على مزيد من التفاصيل.

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

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

كائن DateTimeInput
dateTimeInput.hasDate boolean
true إذا كان التاريخ والوقت المُدخلان يتضمّنان تاريخًا، إذا كان false يتضمّن وقتًا فقط.
dateTimeInput.hasTime boolean
true إذا كان تاريخ ووقت الإدخال يتضمّن وقتًا، إذا كان false يتضمّن تاريخًا فقط.
dateTimeInput.msSinceEpoch string
الوقت الذي اختاره المستخدم، بالمللي ثانية منذ بدء حساب الوقت (00:00:00 بالتوقيت العالمي المنسق في 1 كانون الثاني (يناير) 1970).
كائن DateInput
dateInput.msSinceEpoch string
الوقت الذي اختاره المستخدم، بالمللي ثانية منذ بدء حساب الوقت (00:00:00 بالتوقيت العالمي المنسق في 1 كانون الثاني (يناير) 1970).
عنصر TimeInput
timeInput.hours number
رقم الساعة الذي اختاره المستخدم.
timeInput.minutes number
عدد الدقائق الذي يختاره المستخدم.

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

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

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

عنصر حدث التقويم
calendar.attendees[] list of attendee objects
البيانات التي ينشئها المستخدمون: قائمة بالضيوف في حدث التقويم
calendar.calendarId string
معرّف التقويم
calendar.capabilities object
البيانات التي ينشئها المستخدمون: عنصر يصف إمكانات الإضافة لعرض معلومات الحدث أو تعديلها
calendar.capabilities.canAddAttendees boolean
البيانات التي ينشئها المستخدمون: true إذا كانت الإضافة يمكنها إضافة ضيوف جدد إلى قائمة ضيوف الحدث، false في غير ذلك
calendar.capabilities.canSeeAttendees boolean
البيانات التي ينشئها المستخدمون: true إذا كانت الإضافة قادرة على قراءة قائمة ضيوف الفعالية false بخلاف ذلك
calendar.capabilities.canSeeConferenceData boolean
البيانات التي ينشئها المستخدمون: true إذا كانت الإضافة يمكنها قراءة بيانات مكالمة الفيديو الخاصة بالحدث false في غير ذلك
calendar.capabilities.canSetConferenceData boolean
البيانات التي ينشئها المستخدمون: true إذا كانت الإضافة يمكنها تعديل بيانات مؤتمر الحدث false بخلاف ذلك
calendar.capabilities.canAddAttachments boolean
البيانات التي ينشئها المستخدمون: true إذا كانت الإضافة يمكنها إضافة مرفقات جديدة إلى الحدث، false بخلاف ذلك.
calendar.conferenceData Conference data object
البيانات التي ينشئها المستخدمون: عنصر يمثّل أي بيانات مؤتمر مرتبطة بهذا الحدث، مثل تفاصيل مؤتمر Google Meet
calendar.id string
رقم تعريف الحدث.
calendar.organizer object
عنصر يمثّل منظّم الحدث
calendar.organizer.email string
عنوان البريد الإلكتروني لمُنظِّم الحدث.
calendar.recurringEventId string
رقم تعريف حدث متكرّر.

الضيف

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

عنصر الضيف
attendee.additionalGuests number
عدد الضيوف الإضافيين الذين أشار المدعو إلى أنّه سيحضرهم القيمة التلقائية هي صفر.
attendee.comment string
تعليق الردّ من الحاضر، إن وُجد.
attendee.displayName string
الاسم المعروض للمشارك.
attendee.email string
عنوان البريد الإلكتروني للمشارك.
attendee.optional boolean
true إذا تم وضع علامة على حضور هذا الضيف على أنّه اختياري، false في غير ذلك
attendee.organizer boolean
true إذا كان الضيف هو أحد منظّمي هذا الحدث.
attendee.resource boolean
true إذا كان الحاضر يمثّل موردًا، مثل غرفة أو قطعة من المعدّات false في غير ذلك
attendee.responseStatus string
حالة ردّ الضيف. تشمل القيم المحتمَلة ما يلي:
  • accepted: قبِل الضيف دعوة الحدث.
  • declined: رفض الحاضر دعوة حضور الحدث.
  • needsAction: لم يردّ الحاضر على دعوة الفعالية.
  • tentative: وافق الحاضر مبدئيًا على دعوة حضور الحدث.
attendee.self boolean
true إذا كان هذا الضيف يمثّل التقويم الذي يظهر فيه هذا الحدث، false في غير ذلك

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

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

كائن بيانات المؤتمر
conferenceData.conferenceId string
رقم تعريف مكالمة الفيديو. يهدف هذا المعرّف إلى السماح للتطبيقات بتتبُّع المؤتمرات، ويجب عدم عرض هذا المعرّف للمستخدمين.
conferenceData.conferenceSolution object
عنصر يمثّل حلّ المؤتمرات، مثل Hangouts أو Google Meet
conferenceData.conferenceSolution.iconUri string
معرّف الموارد المنتظم للرمز المرئي للمستخدمين والذي يمثّل حلّ المؤتمرات هذا.
conferenceData.conferenceSolution.key object
المفتاح الذي يحدِّد بشكل فريد حلّ المؤتمرات لهذا الحدث.
conferenceData.conferenceSolution.key.type string
نوع منصة مكالمات الفيديو. تشمل القيم المحتمَلة ما يلي:
  • eventHangout لتطبيق Hangouts المخصّص للمستهلكين (http://hangouts.google.com).
  • eventNamedHangout لتطبيق Hangouts الكلاسيكي لمستخدمي Google Workspace (http://hangouts.google.com).
  • hangoutsMeet لتطبيق Google Meet (http://meet.google.com).
conferenceData.conferenceSolution.name string
الاسم الذي يظهر للمستخدمين لحلّ المكالمات الجماعية هذا (غير مترجَم).
conferenceData.entryPoints[] list of entry point objects
قائمة نقاط دخول المؤتمر، مثل عناوين URL أو أرقام الهواتف
conferenceData.notes string
ملاحظات إضافية (مثل تعليمات من مشرف النطاق أو إشعارات قانونية) حول المكالمة التي ينبغي عرضها للمستخدم يمكن أن يحتوي على لغة HTML. الحد الأقصى للطول هو 2048 حرفًا.
conferenceData.parameters object
كائن يحتوي على خريطة لبيانات المَعلمات المحدّدة لاستخدامها في الإضافة
conferenceData.parameters.addOnParameters object
خريطة مفاتيح سلاسل المَعلمات وقيمها يحدّد مطوّر الإضافة هذه المفاتيح والقيم لإرفاق معلومات بمؤتمر معيّن لاستخدام الإضافة.

نقطة الإدخال

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

عنصر نقطة الدخول
entryPoint.accessCode string
رمز الوصول المستخدَم للوصول إلى المؤتمر. الحد الأقصى لعدد الأحرف المسموح به هو 128 حرفًا. لا يستخدم مقدّمو المؤتمرات عادةً سوى مجموعة فرعية من {accessCode, meetingCode, passcode, password, pin} لمنح إذن بالوصول إلى المؤتمرات. مطابقة الحقول التي يستخدمها مقدّم خدمة المكالمات الجماعية وعرضها فقط
entryPoint.entryPointFeatures list
ميزات نقطة الدخول في الوقت الحالي، تنطبق هذه الميزات على نقاط دخول phone فقط:
  • toll: نقطة الدخول هي مكالمة هاتفية مدفوعة.
  • toll_free: نقطة الدخول هي مكالمة هاتفية مجانية.
entryPoint.entryPointType string
نوع نقطة الدخول في ما يلي القيم المحتمَلة:
  • more: تعليمات إضافية للانضمام إلى المؤتمر، مثل أرقام الهواتف البديلة يمكن أن يحتوي الاجتماع على نقطة دخول واحدة فقط more، وإذا كان متوفّرًا، يجب أيضًا توفّر نوع واحد على الأقل من نقاط الدخول.
  • phone: الانضمام إلى المؤتمر عبر رقم هاتف يمكن أن يحتوي المؤتمر على صفر أو أكثر من نقاط إدخال phone. لا يعرض "تقويم Google" سوى أول نقطتَي دخول للهاتف، بعد التنسيق والترتيب أبجديًا.
  • sip: الانضمام إلى المؤتمر عبر بروتوكول بدء الجلسة (SIP) يمكن أن يحتوي الاجتماع على نقطة دخول واحدة sip كحد أقصى.
  • video: الانضمام إلى المؤتمر عبر HTTP يمكن أن يحتوي الاجتماع على نقطة دخول واحدة video كحد أقصى.
entryPoint.label string
التصنيف المرئي للمستخدم لمعرّف الموارد المنتظم لنقطة الدخول (غير مترجَم).
entryPoint.meetingCode string
رمز الاجتماع المستخدَم للوصول إلى المؤتمر. الحد الأقصى لعدد الأحرف المسموح به هو 128 حرفًا. لا يستخدم مقدّمو المؤتمرات عادةً سوى مجموعة فرعية من {accessCode, meetingCode, passcode, password, pin} لمنح إذن بالوصول إلى المؤتمرات. مطابقة الحقول التي يستخدمها مقدّم خدمة المكالمات الجماعية وعرضها فقط
entryPoint.passcode string
رمز المرور المستخدَم للوصول إلى المؤتمر الحد الأقصى لعدد الأحرف المسموح به هو 128 حرفًا. لا يستخدم مقدّمو المؤتمرات عادةً سوى مجموعة فرعية من {accessCode, meetingCode, passcode, password, pin} لمنح إذن الوصول إلى المؤتمرات. مطابقة الحقول التي يستخدمها مقدّم خدمة المكالمات الجماعية وعرضها فقط
entryPoint.password string
كلمة المرور المستخدَمة للوصول إلى المؤتمر الحد الأقصى لعدد الأحرف المسموح به هو 128 حرفًا. لا يستخدم مقدّمو المؤتمرات عادةً سوى مجموعة فرعية من {accessCode, meetingCode, passcode, password, pin} لمنح إذن بالوصول إلى المؤتمرات. مطابقة الحقول التي يستخدمها مقدّم خدمة المكالمات الجماعية وعرضها فقط
entryPoint.pin string
رقم التعريف الشخصي المستخدَم للوصول إلى المؤتمر. الحد الأقصى لعدد الأحرف المسموح به هو 128 حرفًا. لا يستخدم مقدّمو المؤتمرات عادةً سوى مجموعة فرعية من {accessCode, meetingCode, passcode, password, pin} لمنح إذن بالوصول إلى المؤتمرات. مطابقة الحقول التي يستخدمها مقدّم خدمة المكالمات الجماعية وعرضها فقط
entryPoint.regionCode string
رمز المنطقة التي يقع فيها رقم الهاتف. مطلوب من المستخدمين إذا لم يتضمّن معرّف الموارد المنتظم رمز بلد. تستند القيم إلى القائمة العلنية لقائمة رموز المناطق في CLDR.
entryPoint.uri string
معرّف الموارد المنتظم (URI) لنقطة الدخول. الحد الأقصى لعدد الأحرف هو 1300 حرف. يعتمد التنسيق على نوع نقطة الإدخال:
  • more: يجب توفّر مخطّط http: أو https:.
  • phone: يجب توفُّر مخطّط tel:. يجب أن يتضمّن معرّف الموارد المتّصل (URI) تسلسل الاتصال بالكامل (على سبيل المثال، "tel:+12345678900,,,12345678;1234").
  • sip: يجب توفّر مخطّط sip: أو sips:. على سبيل المثال، "sip:12345678@myprovider.com".
  • video: يجب توفّر مخطّط http: أو https:.

عنصر حدث Drive

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

عنصر حدث Drive
drive.activeCursorItem Drive item object
العنصر في Drive مفعَّل حاليًا.
drive.selectedItems[] list of Drive item objects
قائمة بالعناصر (الملفات أو المجلدات) التي تم اختيارها في Drive

ملف في Drive

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

عنصر ملف في Drive
item.addonHasFileScopePermission boolean
إذا كان القيمة هي true، يعني ذلك أنّ الإضافة قد طلبت وتلقّت إذن نطاق https://www.googleapis.com/auth/drive.file لهذا العنصر، وإلا سيكون هذا الحقل هو false.
item.id string
معرّف السلعة المحدّدة.
item.iconUrl string
عنوان URL للرمز الذي يمثّل العنصر المحدّد
item.mimeType string
نوع MIME للعنصر المحدّد.
item.title string
عنوان العنصر المحدّد.

عنصر حدث Gmail

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

عنصر حدث Gmail
gmail.accessToken string
رمز الوصول المخصّص لخدمة Gmail. يمكنك استخدام هذا الرمز المميّز مع GmailApp.setCurrentMessageAccessToken(accessToken) طريقة منح الإضافة إذن وصول مؤقتًا إلى رسالة Gmail المفتوحة حاليًا للمستخدم أو السماح للإضافة بإنشاء مسودات جديدة.
gmail.bccRecipients[] list of strings
غير مفعَّل تلقائيًا. قائمة بعنوانات البريد الإلكتروني للمستلمين في "نسخة مخفية الوجهة" والمضمّنة حاليًا في مسودة تعدّها الإضافة لتفعيل هذا الحقل، عليك ضبط الحقل addOns.gmail.composeTrigger.draftAccess في ملف البيان على METADATA.
gmail.ccRecipients[] list of strings
غير مفعَّل تلقائيًا. قائمة بعنوانات البريد الإلكتروني للمستلمين في حقل "نسخة إلى" والمضمّنة حاليًا في مسودة تتم صياغتها من خلال الإضافة لتفعيل هذا الحقل، يجب ضبط الحقل addOns.gmail.composeTrigger.draftAccess في ملف البيان على METADATA.
gmail.messageId string
رقم تعريف رسالة Gmail المفتوحة حاليًا.
gmail.threadId string
معرّف سلسلة محادثات Gmail المفتوحة حاليًا.
gmail.toRecipients[] list of strings
غير مفعَّل تلقائيًا. قائمة بعنوانات البريد الإلكتروني للمستلمين في حقل "إلى:" والمضمّنة حاليًا في مسودة تتم صياغتها من خلال الإضافة لتفعيل هذا الحقل، عليك ضبط الحقل addOns.gmail.composeTrigger.draftAccess في ملف البيان على METADATA.

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

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

عنصر حدث "مستندات Google"
docs.id string
لا يظهر هذا الحقل إلا إذا منح المستخدم الإذن بنطاق https://www.googleapis.com/auth/drive.file.
رقم تعريف المستند المفتوح في واجهة مستخدم "مستندات Google".
docs.title string
لا يظهر إلا إذا منح المستخدم الإذن بنطاق https://www.googleapis.com/auth/drive.file.
عنوان المستند الذي تم فتحه في واجهة مستخدم "مستندات Google".
docs.addonHasFileScopePermission boolean
في حال true، طلبت الإضافة إذن نطاق https://www.googleapis.com/auth/drive.file للمستند المفتوح في واجهة مستخدم "مستندات Google"، وإلا سيكون قيمة الحقل هذا هي false.
docs.matchedUrl.url string
لا يظهر هذا الحقل إلا في حال استيفاء الشروط التالية:
  • تم تفويض https://www.googleapis.com/auth/workspace.linkpreview من قِبل المستخدم.
  • يتطابق عنوان URL مع نمط المضيف المحدّد في عامل تشغيل LinkPreviewTriggers.

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

مثال على الحمولة عندما يُعاين المستخدم الرابط https://www.example.com/12345: 

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

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

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

عنصر حدث "جداول بيانات Google"
sheets.id string
لا يظهر هذا الحقل إلا إذا منح المستخدم الإذن بنطاق https://www.googleapis.com/auth/drive.file. رقم تعريف جدول البيانات المفتوح في واجهة مستخدم "جداول بيانات Google"
sheets.title string
لا يظهر هذا الحقل إلا إذا منح المستخدم الإذن بنطاق https://www.googleapis.com/auth/drive.file. عنوان جدول البيانات الذي تم فتحه في واجهة مستخدم "جداول بيانات Google"
sheets.addonHasFileScopePermission boolean
إذا كان true، تكون الإضافة قد طلبت وتلقّت إذن نطاق https://www.googleapis.com/auth/drive.file لجدول البيانات المفتوح في واجهة مستخدم "جداول بيانات Google"، وإلا يكون هذا الحقل false.
sheets.matchedUrl.url string
لا يظهر هذا الحقل إلا في حال استيفاء الشروط التالية:
  • تم تفويض https://www.googleapis.com/auth/workspace.linkpreview من قِبل المستخدم.
  • يتطابق عنوان URL مع نمط المضيف المحدّد في عامل تشغيل LinkPreviewTriggers.

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

مثال على الحمولة عندما يُعاين المستخدم الرابط https://www.example.com/12345:

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

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

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

عنصر حدث "العروض التقديمية من Google"
slides.id string
لا يظهر هذا الحقل إلا إذا منح المستخدم الإذن بنطاق https://www.googleapis.com/auth/drive.file. رقم تعريف العرض التقديمي المفتوح في واجهة مستخدم "العروض التقديمية من Google"
slides.title string
لا يظهر هذا الحقل إلا إذا منح المستخدم الإذن بنطاق https://www.googleapis.com/auth/drive.file. عنوان العرض التقديمي الذي تم فتحه في شريط أدوات "العروض التقديمية من Google"
slides.addonHasFileScopePermission boolean
إذا كان true، طلبت الإضافة إذن نطاق https://www.googleapis.com/auth/drive.file وتلقّته للعرض التقديمي المفتوح في واجهة مستخدم "العروض التقديمية من Google"، وإلا سيكون هذا الحقل false.
slides.matchedUrl.url string
لا يظهر هذا الحقل إلا في حال استيفاء الشروط التالية:
  • تم تفويض https://www.googleapis.com/auth/workspace.linkpreview من قِبل المستخدم.
  • يتطابق عنوان URL مع نمط المضيف المحدّد في عامل تشغيل LinkPreviewTriggers.

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

مثال على الحمولة عندما يُعاين المستخدم الرابط https://www.example.com/12345:

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