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

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

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

القيود

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

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

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

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

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

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

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

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

مشغِّلات الأحداث

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

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

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

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

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

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

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

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

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

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

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

المشغّلات/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. لحذف مشغّل، على يسار المشغّل، انقر على رمز المزيد > حذف المشغّل.

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

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