تتسبب مشغّلات برمجة التطبيقات في تنفيذ دالة نص برمجي محددة (وظيفة المشغّل) كلما حدث حدث محدد. يمكن أن تتسبب أحداث معينة فقط في تنشيط المشغّلات، ويتيح كل تطبيق من تطبيقات Google Workspace مجموعة مختلفة من الأحداث.
عند تنشيط أحد العوامل المشغلة، يتم إنشاء كائن حدث. تحتوي بنية JSON هذه على تفاصيل حول الحدث الذي وقع. يتم تنظيم المعلومات في بنية كائن الحدث بشكل مختلف استنادًا إلى نوع المشغّل.
بعد إنشاء كائن الحدث، يمرره "برمجة التطبيقات" كمَعلمة في دالة trigger. وظيفة المشغِّل هي وظيفة استدعاء يجب تنفيذها بنفسك لاتخاذ الإجراءات المناسبة للاستجابة للحدث. على سبيل المثال، في إضافة Google Workspace التي توسّع نطاق Gmail، يمكنك تحديد مشغِّل ينشئ واجهة بطاقة جديدة عندما يفتح المستخدم سلسلة رسائل. في هذه الحالة، يمكنك تنفيذ وظيفة رد اتصال سياقي لإنشاء البطاقات التي تشكّل واجهة المستخدم الجديدة باستخدام البيانات التي تم تمريرها في كائن الحدث.
تقدّم هذه الصفحة إرشادات حول استخدام المشغّلات في مشاريع إضافة Google Workspace.
مشغلات البيان
على عكس إضافات "محرّر إعلانات Google"، لا يمكن لإضافات Google Workspace في الوقت الحالي استخدام مشغّلات بسيطة لبرمجة التطبيقات. وبدلاً من ذلك، تستخدم إضافات مصمّمة خصيصًا لإضافات Google Workspace: مشغّلات ملفات البيان.
يتم تحديد مشغِّلات البيان بالكامل في بيان إضافة Google Workspace. وتشمل أمثلة مشغِّلات البيان ما يلي:
- مشغّلات الصفحة الرئيسية التي تنشئ الصفحة الرئيسية للإضافة وتعرضها.
- مشغّلات حدث eventOpen في التقويم التي تعرض بطاقة جديدة أو تتخذ إجراءات أخرى عند فتح حدث تقويم.
- مشغّلات أحداث التقويم يتم تشغيلها التي تعرض بطاقة جديدة أو تتخذ إجراءات أخرى عندما يعدّل مستخدم حدث تقويم ويحفظه.
- مشغّلات Drive onItemsSelected التي تعرض بطاقة جديدة أو تتخذ إجراءات أخرى عندما يختار مستخدم ملفًا أو مجلدًا واحدًا أو أكثر في Drive.
- عوامل تشغيل الإنشاء في Gmail التي تعرض بطاقة إضافة عندما يفتح المستخدم الإضافة في نافذة الإنشاء في Gmail.
- مشغّلات Gmail السياقية التي تعرض بطاقة جديدة أو تتخذ إجراءات أخرى عندما يفتح المستخدم رسالة Gmail.
- المشغّلات على onFileScopeGranted التي تعرض بطاقة جديدة عندما يمنح المستخدمون تفويضًا لنطاق OAuth
drive.fileفي مستند المحرر الحالي.
في القائمة أعلاه، تكون عوامل تشغيل الصفحة الرئيسية فقط هي التي لا تستند إلى السياق، والباقي هي عوامل تشغيل سياقية. راجع البيان لمزيد من المعلومات حول تعريفات تشغيل البيان.
بالإضافة إلى مشغلات البيان، يمكن لإضافات Google Workspace أيضًا استخدام مشغّلات قابلة للتثبيت في "برمجة تطبيقات Google".
القيود
هناك قيود مفروضة على استخدام مشغلات البيان.
- لا يتم استخدام عوامل التشغيل هذه إلا في مشاريع إضافة Google Workspace، وليس لها أي غرض في أي تطبيق آخر.
- ونظرًا لأنه تم تحديدها في بيان الإضافة وليس في رمزها، لا يمكنك استخدام خدمة برمجة التطبيقات
Scriptلإنشاء عوامل التشغيل هذه أو تعديلها. - لا يمكن أن تتضمن العوامل المشغِّلة للسياق في Gmail حاليًا إلا معايير
unconditional. وهذا يعني أنّه يتم تشغيل المشغّلات السياقية لكل رسالة إلكترونية، بغض النظر عن المحتوى. - لا يمكن أن يكون لكل إضافة سوى عامل تشغيل واحد من كل نوع، ولكل مستخدم، لكل مستند.