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

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

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

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