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

בדומה לטריגרים פשוטים, טריגרים שאפשר להתקין מאפשרים ל-Apps Script להריץ פונקציה באופן אוטומטי כשאירוע מסוים, כמו פתיחת מסמך,. עם זאת, טריגרים שאפשר להתקין הם גמישים יותר מטריגרים פשוטים: הם יכולים לקרוא לשירותים שדורשים הרשאה, הם מציעים כמה סוגים נוספים של אירועים, כולל טריגרים מבוססי-זמן (שעון), וניתן לשלוט בהם באופן פרוגרמטי. גם לטריגרים פשוטים וגם לטריגרים שאפשר להתקין, 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. כדי למחוק טריגר, משמאל לטריגר לוחצים על סמל האפשרויות הנוספות > Delete trigger

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

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