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

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

القيود

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

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

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

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

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

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

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

في ما يلي مثال على تطبيق Google Chat ينشر رسالة كل دقيقة على كل مساحة تتوفّر فيها التطبيق:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

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

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

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

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

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

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

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

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

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

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

يمكنك أيضًا إنشاء مشغّلات وحذفها آليًا باستخدام خدمة النص البرمجي. ابدأ بالاتصال بـ 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;
    }
  }
}

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

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

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

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

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

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