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

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

القيود

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

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

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

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

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

  • تخضع عوامل التشغيل القابلة للتثبيت لالحدود القصوى لحصص عوامل التشغيل في Apps Script.

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

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

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

إدارة عوامل التفعيل يدويًا

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

  1. افتح مشروعك في Apps Script.
  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;
    }
  }
}

الأخطاء في عوامل التفعيل

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

بدلاً من ذلك، ترسل لك Apps Script رسالة إلكترونية على النحو التالي:

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.