العوامل المشغِّلة القابلة للتثبيت

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

القيود

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

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

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

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

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

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

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

العوامل المشغِّلة المستندة إلى الحدث

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

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

هناك العديد من عوامل التشغيل القابلة للتثبيت Google Workspace للتطبيقات:

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

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

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

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

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

إدارة العوامل المشغِّلة آليًا

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

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

المشغلات/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.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.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;
    }
  }
}

أخطاء في العوامل المشغِّلة

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

بدلاً من ذلك، ترسل لك "برمجة التطبيقات" رسالة إلكترونية مثل ما يلي:

From: apps-scripts-notifications@google.com
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. لحذف عامل تشغيل، على يسار المشغِّل، انقر على رمز المزيد &gt؛ حذف المشغِّل.

مشغِّلات الإضافات القابلة للتثبيت في الإضافات

لمزيد من المعلومات حول استخدام العوامل القابلة للتثبيت في الإضافات، يُرجى الاطّلاع على مشغّلات الإضافات.