טריגרים ניתנים להתקנה

בדומה לטריגרים פשוטים, טריגרים שאפשר להתקין מאפשרים Apps Script מריץ פונקציה באופן אוטומטי כשאירוע מסוים כמו פתיחת מסמך. עם זאת, טריגרים שניתנים להתקנה מציעים יותר מאשר טריגרים פשוטים: הם יכולים להתקשר services שמצריכות הרשאה, הם מציעים כמה סוגים נוספים של אירועים, כולל אירועים מבוססי-זמן (שעון) טריגרים, וניתן לשלוט בהם באופן פרוגרמטי. גם למודעות פשוטות וגם טריגרים שאפשר להתקין, Apps Script מעביר את הפונקציה המופעלת ה אובייקט אירוע שמכיל מידע לגבי ההקשר שבו התרחש האירוע.

הגבלות

למרות שטריגרים שניתנים להתקנה יש יותר גמישות מטריגרים פשוטים, הם עדיין כפופים למספר הגבלות:

  • הן לא פועלות אם הקובץ נפתח במצב קריאה בלבד (הצגה או תגובה). עבור סקריפטים עצמאיים, משתמשים צריכים לפחות גישת צפייה לקובץ הסקריפט כדי שהטריגרים יפעלו בצורה תקינה.

  • הפעלות של סקריפטים ובקשות API לא גורמות להרצה של טריגרים. לדוגמה, שיחות FormResponse.submit() שליחה של תשובה חדשה לטופס לא גורמת לטריגר של שליחת הטופס לפעול.

  • טריגרים שאפשר להתקין תמיד פועלים בחשבון של המשתמש שיצר אותם. לדוגמה, אם יוצרים טריגר פתוח שניתן להתקנה, הוא יריץ כשהקולגה שלכם פותח את המסמך (אם לקולגה שלכם יש גישת עריכה), אבל הוא פועל בתור החשבון שלכם. המשמעות היא שאם תיצרו טריגר שליחת אימייל כשמסמך נפתח, האימייל תמיד נשלח מאת החשבון שלך, לא בהכרח החשבון שפתח את המסמך. אבל, לפעמים אפשר ליצור טריגר להתקנה בכל חשבון, וזה יגרום באימייל אחד שנשלח מכל חשבון.

  • חשבון נתון לא יכול לראות טריגרים שהותקנו מחשבון שני, אפילו למרות שהחשבון הראשון עדיין יכול להפעיל את הטריגרים האלה.

  • טריגרים שניתנים להתקנה כפופים לטריגר של Apps Script מכסות המכסה.

טריגרים שמבוססים על זמן

טריגר מבוסס-זמן (נקרא גם טריגר בשעון) דומה משימת cron ב-Unix. טריגרים שמבוססים על זמן מאפשרים הסקריפטים מופעלים בפרק זמן מסוים או במרווחי זמן קבועים, באותה תדירות כמו כל דקה או פעם בחודש. (לתשומת ליבך תוסף יכול להשתמש בטריגר מבוסס-זמן פעם בשעה לכל היותר). השעה עשויה להיות מעט אקראי – לדוגמה, אם יוצרים הפעלה חוזרת של השעה 9:00, Apps Script בוחר שעה בין 9:00 ל-10:00, ולאחר מכן שומר שהתזמון עקבי מיום ליום, כך שיעברו 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 Sheets מופעלת בכל פעם שגיליון אלקטרוני נפתח על ידי משתמש שיש לו גישת עריכה, בדיוק כמו הטריגר הפשוט onOpen(). עם זאת, הגרסה הניתנת להתקנה קוראים לשירותים שמחייבים הרשאה. ניתן להתקנה פועלת באישור המשתמש שיצר את הטריגר, אפילו אם משתמש אחר עם גישת עריכה פותח את הגיליון האלקטרוני.

יש כמה טריגרים שניתנים להתקנה עבור Google Workspace אפליקציות:

  • טריגר פתוח שניתן להתקנה פועל כשמשתמש פותח גיליון אלקטרוני, מסמך או טופס שיש להם הרשאה לערוך.
  • טריגר עריכה שניתן להתקנה פועל כשמשתמש משנה ערך גיליון אלקטרוני.
  • טריגר שינוי שניתן להתקנה פועל כשמשתמש משנה את המבנה של הגיליון האלקטרוני עצמו - לדוגמה, על ידי הוספת גיליון חדש או הסרת עמודה.
  • טריגר לשליחת טופס שניתן להתקנה פועל כשמשתמש משיב לטופס. יש שתי גרסאות של הטריגר לשליחת טופס, אחד ל-Google Forms והמזהה הוא ב-Sheets אם הטופס נשלח לגיליון אלקטרוני.
  • טריגר של אירוע ביומן שניתן להתקנה פועל בכל פעם שיש אירוע ביומן של משתמש עודכנו - נוצרו, נערכו או נמחקו.

אפשר להשתמש בטריגרים שניתנים להתקנה בסקריפטים עצמאיים וקשורים. לדוגמה, סקריפט עצמאי יכול ליצור באופן פרוגרמטי טריגר להתקנה עבור קובץ Google Sheets שרירותי באמצעות קריאה TriggerBuilder.forSpreadsheet(key) ולהעביר את המזהה של הגיליון האלקטרוני.

ניהול טריגרים באופן ידני

כדי ליצור באופן ידני טריגר שניתן להתקנה בעורך הסקריפטים: יש לבצע את השלבים הבאים:

  1. פותחים את פרויקט Apps Script.
  2. בצד ימין, לוחצים על טריגרים .
  3. בפינה השמאלית התחתונה, לוחצים על הוספת טריגר.
  4. בוחרים ומגדירים את סוג הטריגר שרוצים ליצור.
  5. לוחצים על שמירה.

ניהול טריגרים באופן פרוגרמטי

אפשר ליצור ולמחוק טריגרים באופן פרוגרמטי באמצעות שירות סקריפטים. מתחילים בהתקשרות ScriptApp.newTrigger(functionName), שמחזירה TriggerBuilder

הדוגמה הבאה ממחישה איך ליצור שני טריגרים שמבוססים על זמן – אחד מופעלת מדי 6 שעות, ודלק שמופעל בכל יום שני בשעה 9:00 (באזור הזמן) שהסקריפט מוגדר אליו).

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. בצד ימין, לוחצים על הטריגרים שלי.

  3. כדי למחוק טריגר, בצד שמאל של הטריגר, לוחצים על סמל האפשרויות הנוספות > מחיקת הטריגר.

טריגרים בתוספים

בנוסף לטריגרים שניתנים להתקנה, אפשר להשתמש בטריגרים של מניפסטים תוספים. לקבלת מידע נוסף, לראות טריגרים לתוספים ל-Google Workspace.