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