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

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

الشروط

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

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

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

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

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

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

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

يتشابه عامل التشغيل المستند إلى الوقت (المعروف أيضًا باسم مشغل الساعة) مع مهمة cron في نظام التشغيل Unix. تتيح المشغلات المستندة إلى الوقت تنفيذ النصوص البرمجية في وقت معين أو على فاصل زمني متكرر، سواء بشكل متكرر كل دقيقة أو بشكل غير متكرر مرة واحدة في الشهر. (يُرجى العلم أنّ الإضافة يمكن أن تستخدم مشغلًا مستندًا إلى الوقت مرة واحدة في الساعة على الأكثر). قد يكون الوقت عشوائيًا إلى حد ما - على سبيل المثال، إذا أنشأت مشغلاً متكررًا في الساعة 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 :

يمكنك استخدام عوامل التشغيل القابلة للتثبيت في النصوص البرمجية المستقلة والمرتبطة. على سبيل المثال، يمكن لنص برمجي مستقل إنشاء مشغل قابل للتثبيت لملف عشوائي في "جداول بيانات 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. لحذف عامل تشغيل، على يسار المشغّل، انقر على رمز المزيد > حذف المشغِّل.

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

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