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

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

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

محدودیت‌ها

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

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

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

    یک استثنا برای این محدودیت، Form.submitGrades() است. اگر کد شما از تریگر onFormSubmit استفاده می‌کند، فراخوانی Form.submitGrades() شرط onFormSubmit را فعال می‌کند و باعث ایجاد یک حلقه بی‌نهایت می‌شود. برای جلوگیری از حلقه بی‌نهایت، کدی اضافه کنید که قبل از فراخوانی submitGrades() بررسی کند که آیا نمرات از قبل وجود دارند یا خیر.

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

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

  • تریگرهای قابل نصب تابع محدودیت‌های سهمیه تریگر 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 Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

ایمیل شامل لینکی برای غیرفعال کردن یا پیکربندی مجدد تریگر است. اگر اسکریپت به یک فایل Google Sheets، Docs یا Forms متصل باشد، ایمیل همچنین شامل لینکی به آن فایل است. این لینک‌ها به شما امکان می‌دهند تریگر را غیرفعال کنید یا اسکریپت را برای رفع اشکال ویرایش کنید.

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

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

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

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

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

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

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

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