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