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

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

القيود

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

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

  • لا تؤدي عمليات تنفيذ النصوص البرمجية وطلبات واجهة برمجة التطبيقات إلى تشغيل المشغلات. على سبيل المثال، إنّ استدعاء 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 :

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

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

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

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

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

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

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