المشغلات القابلة للتثبيت

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

القيود

على الرغم من أنّ المشغّلات القابلة للتثبيت توفّر مرونة أكبر من المشغّلات البسيطة، إلا أنّها تخضع لعدة قيود:

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

  • لا تؤدي عمليات تنفيذ النصوص البرمجية وطلبات واجهة برمجة التطبيقات إلى تشغيل المشغّلات. على سبيل المثال، لا يؤدي استدعاء FormResponse.submit() لإرسال رد جديد على النموذج إلى تشغيل مشغّل الإرسال الخاص بالنموذج.

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

  • لا يمكن لحساب معيّن الاطّلاع على المشغّلات المثبّتة من حساب آخر، حتى إذا كان الحساب الأول لا يزال بإمكانه تفعيل هذه المشغّلات.

  • تخضع المشغّلات القابلة للتثبيت لحدود الحصة الخاصة بمشغّلات "برمجة التطبيقات".

المشغّلات المستندة إلى الوقت

المشغّل المستند إلى الوقت (يُعرف أيضًا باسم مشغّل الساعة) يشبه مهمة cron في نظام التشغيل Unix. تتيح المشغّلات المستندة إلى الوقت تنفيذ البرامج النصية في وقت معيّن أو على فترات متكررة، وذلك بشكل متكرر كل دقيقة أو بشكل غير متكرر مرة واحدة في الشهر. (يُرجى العِلم أنّه يمكن أن يستخدم الملحق مشغّلاً يستند إلى الوقت مرة واحدة في الساعة كحد أقصى). قد يتم تحديد الوقت بشكل عشوائي قليلاً. على سبيل المثال، إذا أنشأت مشغّلاً متكررًا في الساعة 9 صباحًا، سيختار Apps Script وقتًا بين الساعة 9 صباحًا و10 صباحًا، ثم سيحافظ على هذا التوقيت ثابتًا من يوم إلى آخر حتى تمر 24 ساعة قبل تشغيل المشغّل مرة أخرى.

المشغّلات المستندة إلى الأحداث

تتشابه المشغّلات المستندة إلى الأحداث والقابلة للتثبيت من الناحية النظرية مع المشغّلات البسيطة مثل onOpen()، ولكن يمكنها الاستجابة لأحداث إضافية، كما أنّها تتصرف بشكل مختلف.

على سبيل المثال، يتم تفعيل مشغّل التثبيت المفتوح في "جداول بيانات Google" عندما يفتح أي مستخدم لديه إذن تعديل جدول البيانات، تمامًا مثل المشغّل البسيط onOpen(). ومع ذلك، يمكن للنسخة القابلة للتثبيت استدعاء الخدمات التي تتطلّب تفويضًا. يتم تشغيل الإصدار القابل للتثبيت بإذن المستخدم الذي أنشأ المشغّل، حتى إذا فتح مستخدم آخر لديه إذن التعديل جدول البيانات.

تتوفّر عدة مشغّلات قابلة للتثبيت للتطبيقاتGoogle Workspace :

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

يمكنك استخدام المشغّلات القابلة للتثبيت في النصوص البرمجية المستقلة والمرتبطة. على سبيل المثال، يمكن لنص برمجي مستقل إنشاء مشغّل قابل للتثبيت بشكل آلي لملف عشوائي في "جداول بيانات Google" من خلال استدعاء TriggerBuilder.forSpreadsheet(key) وتمرير معرّف جدول البيانات.

إدارة المشغّلات يدويًا

لإنشاء مشغّل قابل للتثبيت يدويًا في محرّر النصوص البرمجية، اتّبِع الخطوات التالية:

  1. افتح مشروعك في "برمجة تطبيقات Google".
  2. على يمين الصفحة، انقر على العوامل المشغِّلة .
  3. في أسفل يسار الصفحة، انقر على إضافة مشغّل.
  4. اختَر نوع المشغّل الذي تريد إنشاءه واضبطه.
  5. انقر على حفظ.

إدارة المشغّلات آليًا

يمكنك أيضًا إنشاء المشغّلات وحذفها آليًا باستخدام خدمة "برمجة Google". ابدأ بإجراء مكالمة إلى ScriptApp.newTrigger(functionName)، التي تعرض TriggerBuilder.

يوضّح المثال التالي كيفية إنشاء مشغّلين مستندَين إلى الوقت، أحدهما يتم تشغيله كل 6 ساعات، والآخر يتم تشغيله كل اثنين في الساعة 9 صباحًا (في المنطقة الزمنية التي تم ضبط النص البرمجي عليها).

triggers/triggers.gs
/**  * Creates two time-driven triggers.  * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers  */ function createTimeDrivenTriggers() {   // Trigger every 6 hours.   ScriptApp.newTrigger('myFunction')       .timeBased()       .everyHours(6)       .create();   // Trigger every Monday at 09:00.   ScriptApp.newTrigger('myFunction')       .timeBased()       .onWeekDay(ScriptApp.WeekDay.MONDAY)       .atHour(9)       .create(); }

يوضّح المثال التالي كيفية إنشاء مشغّل مفتوح قابل للتثبيت لجداول البيانات. يُرجى العِلم أنّه على عكس مشغّل onOpen() بسيط، لا يلزم ربط البرنامج النصي للمشغّل القابل للتثبيت بجدول البيانات. لإنشاء هذا المشغّل من نص برمجي مستقل، ما عليك سوى استبدال SpreadsheetApp.getActive() باستدعاء SpreadsheetApp.openById(id).

triggers/triggers.gs
/**  * Creates a trigger for when a spreadsheet opens.  * @see https://developers.google.com/apps-script/guides/triggers/installable  */ function createSpreadsheetOpenTrigger() {   const ss = SpreadsheetApp.getActive();   ScriptApp.newTrigger('myFunction')       .forSpreadsheet(ss)       .onOpen()       .create(); }

لتعديل مشغّل قابل للتثبيت حالي آليًا، عليك حذفه وإنشاء مشغّل جديد. إذا سبق لك تخزين رقم تعريف مشغّل، يمكنك حذفه من خلال تمرير رقم التعريف كمعلَمة إلى الدالة أدناه.

triggers/triggers.gs
/**  * Deletes a trigger.  * @param {string} triggerId The Trigger ID.  * @see https://developers.google.com/apps-script/guides/triggers/installable  */ function deleteTrigger(triggerId) {   // Loop over all triggers.   const allTriggers = ScriptApp.getProjectTriggers();   for (let index = 0; index < allTriggers.length; index++) {     // If the current trigger is the correct one, delete it.     if (allTriggers[index].getUniqueId() === triggerId) {       ScriptApp.deleteTrigger(allTriggers[index]);       break;     }   } }

قبل إنشاء مشغّل، ننصحك بالتأكّد من أنّ الدالة المرتبطة تتضمّن جميع أذونات OAuth اللازمة.

أخطاء في المشغّلات

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

بدلاً من ذلك، يرسل إليك Apps Script رسالة إلكترونية على النحو التالي:

From: [email protected] Subject: Summary of failures for Google Apps Script Your script has recently failed to finish successfully. A summary of the failure(s) is shown below.

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

لمراجعة جميع المشغّلات المرتبطة بحسابك على Google وإيقاف المشغّلات التي لم تعُد بحاجة إليها، اتّبِع الخطوات التالية:

  1. انتقِل إلى script.google.com.
  2. على يمين الشاشة، انقر على العوامل المشغِّلة.

  3. لحذف مشغّل، انقر على "المزيد" > حذف المشغّل على يسار المشغّل.

المشغّلات في الإضافات

بالإضافة إلى المشغّلات القابلة للتثبيت، يمكنك استخدام مشغّلات البيان في الإضافات. لمزيد من المعلومات، راجِع مشغّلات إضافات Google Workspace.