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

בדומה לטריגרים פשוטים, טריגרים שניתן להתקין מאפשרים להריץ פונקציה ב-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 (באזור הזמן שמוגדר לסקריפט).

Enable/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();
}

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

Enable/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.