تریگرهای قابل نصب

مانند راه‌اندازهای ساده ، تریگرهای قابل نصب به Apps Script اجازه می‌دهند تا زمانی که رویداد خاصی مانند باز کردن یک سند رخ می‌دهد، عملکردی را به‌طور خودکار اجرا کند. با این حال، ماشه‌های قابل نصب، انعطاف‌پذیری بیشتری نسبت به محرک‌های ساده ارائه می‌دهند: آنها می‌توانند خدماتی را که نیاز به مجوز دارند، فراخوانی کنند، چندین نوع رویداد اضافی از جمله راه‌اندازهای زمان‌محور (ساعت) را ارائه می‌دهند، و می‌توان آنها را به صورت برنامه‌ریزی کنترل کرد. برای راه‌اندازهای ساده و قابل نصب، Apps Script تابع راه‌اندازی را به یک شی رویداد ارسال می‌کند که حاوی اطلاعاتی درباره زمینه‌ای است که رویداد در آن رخ داده است.

محدودیت های

حتی اگر تریگرهای قابل نصب انعطاف پذیری بیشتری نسبت به تریگرهای ساده ارائه می دهند، همچنان تحت چندین محدودیت هستند:

  • اگر فایلی در حالت فقط خواندنی (مشاهده یا نظر) باز شود، اجرا نمی شوند. برای اسکریپت های مستقل، کاربران حداقل نیاز به مشاهده دسترسی به فایل اسکریپت دارند تا تریگرها به درستی اجرا شوند.

  • اجرای اسکریپت و درخواست های API باعث اجرا شدن تریگرها نمی شود. به عنوان مثال، فراخوانی FormResponse.submit() برای ارسال پاسخ فرم جدید باعث اجرا شدن تریگر ارسال فرم نمی شود.

  • تریگرهای قابل نصب همیشه تحت حساب شخصی که آنها را ایجاد کرده است اجرا می شود. به عنوان مثال، اگر یک تریگر باز قابل نصب ایجاد کنید، زمانی که همکار شما سند را باز می کند (اگر همکار شما دسترسی ویرایش داشته باشد) اجرا می شود، اما به عنوان حساب شما اجرا می شود. این بدان معناست که اگر هنگام باز شدن یک سند، ماشه ای برای ارسال ایمیل ایجاد کنید، ایمیل همیشه از حساب شما ارسال می شود، نه لزوماً حسابی که سند را باز کرده است. با این حال، می‌توانید برای هر حساب یک راه‌انداز قابل نصب ایجاد کنید که منجر به ارسال یک ایمیل از هر حساب می‌شود.

  • یک حساب معین نمی‌تواند محرک‌های نصب‌شده از حساب دوم را ببیند، حتی اگر حساب اول همچنان بتواند آن راه‌اندازها را فعال کند.

  • راه‌اندازهای قابل نصب مشمول محدودیت‌های سهمیه راه‌اندازی Apps Script هستند.

محرک های زمان محور

یک تریگر مبتنی بر زمان (که به آن تریگر ساعت نیز گفته می شود) شبیه به کار cron در یونیکس است. محرک های مبتنی بر زمان به اسکریپت ها اجازه می دهند در یک زمان خاص یا در یک بازه زمانی تکرار شونده، به دفعات هر دقیقه یا به ندرت یک بار در ماه اجرا شوند. (توجه داشته باشید که یک افزونه می‌تواند حداکثر یک بار در ساعت از یک راه‌انداز مبتنی بر زمان استفاده کند.) زمان ممکن است کمی تصادفی باشد - برای مثال، اگر یک ماشه تکراری 9 صبح ایجاد کنید، Apps Script زمانی را بین 9 صبح تا 10 انتخاب می‌کند. AM، سپس این زمان‌بندی را از روز به روز ثابت نگه می‌دارد تا 24 ساعت قبل از اینکه ماشه دوباره شلیک کند، بگذرد.

در زیر نمونه‌ای از برنامه چت Google است که هر دقیقه پیامی را به هر فضایی که برنامه در آن قرار دارد پست می‌کند:

// 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 Sheets هر زمان که صفحه‌گسترده توسط هر کاربری که دسترسی ویرایش دارد باز می‌شود، درست مانند راه‌انداز ساده onOpen() فعال می‌شود. با این حال، نسخه قابل نصب می تواند خدماتی را که نیاز به مجوز دارند تماس بگیرد. نسخه قابل نصب با مجوز کاربری که ماشه را ایجاد کرده است اجرا می شود، حتی اگر کاربر دیگری با دسترسی ویرایش صفحه گسترده را باز کند.

چندین تریگر قابل نصب برای برنامه هایGoogle Workspace وجود دارد:

  • وقتی کاربر صفحه‌گسترده، سند یا فرمی را باز می‌کند که اجازه ویرایش آن را دارد، یک راه‌انداز باز قابل نصب اجرا می‌شود.
  • هنگامی که کاربر مقداری را در صفحه‌گسترده تغییر می‌دهد، یک راه‌انداز ویرایش قابل نصب اجرا می‌شود.
  • یک راه‌انداز تغییر قابل نصب زمانی اجرا می‌شود که کاربر ساختار صفحه‌گسترده خود را تغییر می‌دهد - برای مثال، با افزودن یک صفحه جدید یا حذف یک ستون.
  • یک راه‌انداز ارسال فرم قابل نصب زمانی اجرا می‌شود که کاربر به فرمی پاسخ می‌دهد. دو نسخه از راه‌انداز ارسال فرم وجود دارد، یکی برای خود فرم‌های Google و دیگری برای کاربرگ‌نگار اگر فرم به صفحه‌گسترده ارسال شود .
  • یک راه‌انداز رویداد تقویم قابل نصب زمانی اجرا می‌شود که رویدادهای تقویم کاربر به‌روزرسانی می‌شوند—ایجاد، ویرایش یا حذف می‌شوند.

می توانید از تریگرهای قابل نصب در اسکریپت های مستقل و محدود استفاده کنید. به عنوان مثال، یک اسکریپت مستقل می‌تواند با فراخوانی TriggerBuilder.forSpreadsheet(key) و ارسال شناسه صفحه‌گسترده، یک راه‌انداز قابل نصب برای یک فایل Google Sheets دلخواه به صورت برنامه‌نویسی ایجاد کند.

محرک ها را به صورت دستی مدیریت کنید

برای ایجاد دستی یک تریگر قابل نصب در ویرایشگر اسکریپت، مراحل زیر را دنبال کنید:

  1. پروژه Apps Script خود را باز کنید.
  2. در سمت چپ، روی Triggers کلیک کنید.
  3. در پایین سمت چپ، روی Add Trigger کلیک کنید.
  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 Sheets، Docs یا Forms متصل شده باشد، ایمیل همچنین حاوی پیوندی به آن فایل است. این پیوندها به شما امکان می‌دهند تا تریگر را غیرفعال کنید یا اسکریپت را ویرایش کنید تا باگ را برطرف کنید.

برای بررسی همه محرک‌هایی که با حساب Google شما مرتبط هستند و غیرفعال کردن محرک‌هایی که دیگر به آن نیاز ندارید، این مراحل را دنبال کنید:

  1. به script.google.com بروید.
  2. در سمت چپ، روی My Triggers کلیک کنید.

  3. برای حذف یک ماشه، در سمت راست ماشه، روی More > حذف محرک کلیک کنید.

تریگرهای قابل نصب در افزونه ها

برای اطلاعات بیشتر در مورد استفاده از محرک‌های قابل نصب در افزونه‌ها، به محرک‌های افزودنی مراجعه کنید.