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

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

محدودیت‌ها

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

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

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

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

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

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

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

یک تریگر مبتنی بر زمان (که تریگر ساعت نیز نامیده می‌شود) شبیه به یک cron job در یونیکس است. تریگرهای مبتنی بر زمان به اسکریپت‌ها اجازه می‌دهند در یک زمان خاص یا در یک بازه زمانی تکرارشونده، هر چند دقیقه یا به ندرت هر ماه یک بار، اجرا شوند. (توجه داشته باشید که یک افزونه می‌تواند حداکثر هر ساعت یک بار از تریگر مبتنی بر زمان استفاده کند.) زمان ممکن است کمی تصادفی باشد - برای مثال، اگر یک تریگر تکرارشونده ساعت ۹ صبح ایجاد کنید، Apps Script زمانی بین ۹ صبح و ۱۰ صبح را انتخاب می‌کند، سپس آن زمان‌بندی را از روزی به روز دیگر ثابت نگه می‌دارد تا ۲۴ ساعت قبل از فعال شدن مجدد تریگر سپری شود.

محرک‌های رویداد محور

تریگرهای رویدادمحور قابل نصب از نظر مفهومی شبیه به تریگرهای ساده‌ای مانند onOpen() هستند، اما می‌توانند به رویدادهای اضافی پاسخ دهند و رفتار متفاوتی دارند.

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

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

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

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

مدیریت دستی محرک‌ها

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

  1. پروژه Apps Script خود را باز کنید.
  2. در سمت چپ، روی «فعال کردن زنگ کلیک کنید.
  3. در پایین سمت راست، روی «افزودن ماشه» کلیک کنید.
  4. نوع تریگر مورد نظر برای ایجاد را انتخاب و پیکربندی کنید.
  5. روی ذخیره کلیک کنید.

مدیریت تریگرها به صورت برنامه‌نویسی‌شده

همچنین می‌توانید تریگرها را به صورت برنامه‌نویسی شده با سرویس Script ایجاد و حذف کنید. با فراخوانی ScriptApp.newTrigger(functionName) شروع کنید که یک TriggerBuilder برمی‌گرداند.

مثال زیر نحوه ایجاد دو تریگر زمان‌محور را نشان می‌دهد - یکی که هر ۶ ساعت یکبار فعال می‌شود و دیگری که هر دوشنبه ساعت ۹ صبح (در منطقه زمانی که اسکریپت شما روی آن تنظیم شده است) فعال می‌شود.

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;
    }
  }
}

قبل از ایجاد یک تریگر، توصیه می‌کنیم تأیید کنید که تابع مرتبط تمام مجوزهای لازم OAuth را دارد.

خطاها در تریگرها

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

در عوض، 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 متصل باشد، ایمیل همچنین شامل لینکی به آن فایل است. این لینک‌ها به شما امکان می‌دهند تریگر را غیرفعال کنید یا اسکریپت را برای رفع اشکال ویرایش کنید.

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

  1. به script.google.com بروید.
  2. در سمت چپ، روی «ماشه‌های من» کلیک کنید.
  3. برای حذف یک تریگر، در سمت راست تریگر، روی More > Delete trigger کلیک کنید.

اگر یک تریگر غیرفعال شود، اعلان‌های مربوط به خرابی آن نیز غیرفعال می‌شوند. اعلان‌های خرابی بخش جدایی‌ناپذیر یک تریگر فعال هستند. در نتیجه، برای متوقف کردن دریافت تمام اعلان‌های خرابی برای یک تریگر خاص، باید خود تریگر را غیرفعال یا حذف کنید. در حالی که یک تریگر فعال است، فقط می‌توانید تعداد دفعات این اعلان‌ها را تنظیم کنید.

 Note: Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, you must edit the appropriate script and remove or rename
 the `onOpen()` function.

محرک‌ها در افزونه‌ها

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