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

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

القيود

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

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

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

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

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

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

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

يتشابه المشغل الذي يعتمد على الوقت (ويسمى أيضًا مشغل الساعة) مع لوظيفة cron في نظام التشغيل Unix. تتيح المشغلات المستندة إلى الوقت تنفيذ النصوص البرمجية في وقت معين أو على فاصل زمني متكرر، بشكل متكرر كل دقيقة أو بشكل نادر كمرة واحدة في الشهر. (لاحظ أن ميزة إضافية استخدام مشغل يعتمد على الوقت مرة في الساعة على الأكثر). قد يكون الوقت قليلاً عشوائيًا - على سبيل المثال، إذا قمت بإنشاء مشغل متكرر 9 صباحًا، تختار "برمجة تطبيقات Google" وقتًا بين 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 = '[email protected]';

// 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: [email protected]
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 وألغِ تنشيط المشغلات التي لم تعد بحاجة إليها، اتبع الخطوات التالية:

  1. انتقِل إلى script.google.com.
  2. على يمين الصفحة، انقر على العوامل المشغِّلة.

  3. لحذف عامل تشغيل، على يسار المشغّل، انقر على "المزيد" حذف المشغِّل

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

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