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

בדומה לטריגרים פשוטים, טריגרים שניתנים להתקנה מאפשרים ל-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 לאפליקציות:

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

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

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

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

  1. פותחים את פרויקט Apps Script.
  2. בצד ימין, לוחצים על Triggers (טריגרים) .
  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. בצד ימין, לוחצים על My Triggers (הטריגרים שלי).

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

טריגרים שניתנים להתקנה בתוספים

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