טריגרים פשוטים

טריגרים מאפשרים ל-Apps Script להריץ פונקציה באופן אוטומטי כשאירוע מסוים מתרחש, למשל פתיחת מסמך. טריגרים פשוטים הם קבוצה של פונקציות שמורות שמובנות ב-Apps Script, כמו הפונקציה onOpen(e), שמתבצעת כשמשתמש פותח קובץ ב-Google Docs,‏ Sheets,‏ Slides או Forms. טריגרים שניתן להתקין מציעים יכולות נוספות בהשוואה לטריגרים פשוטים, אבל צריך להפעיל אותם לפני השימוש. בשני סוגי הטריגרים, Apps Script מעביר לפונקציה שהופעל בה אובייקט אירוע שמכיל מידע על ההקשר שבו האירוע התרחש.

תחילת העבודה

כדי להשתמש בטריגר פשוט, פשוט יוצרים פונקציה שמשתמשת באחד משמות הפונקציות האלה ששמורים:

• הפונקציה onOpen(e) פועלת כשמשתמש פותח גיליון אלקטרוני, מסמך, מצגת או טופס שיש לו הרשאה לערוך.
• הפונקציה onInstall(e) פועלת כשמשתמש מתקין תוסף לעריכה מתוך Google Docs,‏ Sheets,‏ Slides או Forms.
• הפונקציה onEdit(e) פועלת כשמשתמש משנה ערך בגיליון אלקטרוני.
• הפונקציה onSelectionChange(e) פועלת כשמשתמש משנה את הבחירה בגיליון אלקטרוני.
• האירוע doGet(e) פועל כשמשתמש מבקר באפליקציית אינטרנט או כשתוכנית שולחת בקשת HTTP GET לאפליקציית אינטרנט.
• הפונקציה doPost(e) פועלת כשתוכנית שולחת בקשת HTTP POST לאפליקציית אינטרנט.

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

הגבלות

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

• הסקריפט צריך להיות מקושר לקובץ ב-Google Sheets, ‏Slides, ‏Docs או Forms, או להיות תוסף שמרחיב את אחת מהאפליקציות האלה.
• הן לא פועלות אם הקובץ נפתח במצב קריאה בלבד (צפייה או תגובה).
• הפעלות של סקריפטים ובקשות ל-API לא גורמות להפעלת טריגרים. לדוגמה, קריאה ל-Range.setValue() כדי לערוך תא לא גורמת להפעלה של הטריגר onEdit בגיליון האלקטרוני.
• הם לא יכולים לגשת לשירותים שדורשים הרשאה. לדוגמה, טריגר פשוט לא יכול לשלוח אימייל כי שירות Gmail דורש הרשאה, אבל טריגר פשוט יכול לתרגם ביטוי באמצעות שירות השפה, שהוא אנונימי.
• הם יכולים לשנות את הקובץ שהם מקושרים אליו, אבל אין להם גישה לקבצים אחרים כי לשם כך נדרשת הרשאה.
• יכול להיות שהם יוכלו לקבוע את הזהות של המשתמש הנוכחי, ויכול להיות שלא, בהתאם לקבוצה מורכבת של הגבלות אבטחה.
• הן לא יכולות לפעול למשך יותר מ-30 שניות.
• בנסיבות מסוימות, תוספים ל-Editor מפעילים את הטריגרים הפשוטים של onOpen(e) ו-onEdit(e) במצב ללא הרשאה, מה שעלול לגרום לבעיות נוספות. מידע נוסף זמין במדריך למחזור החיים של הרשאות התוספים.
• טריגרים פשוטים כפופים למכסות של טריגרים ב-Apps Script.

ההגבלות האלה לא חלות על doGet(e) או על doPost(e).

onOpen(e)

הטריגר onOpen(e) פועל באופן אוטומטי כשמשתמש פותח גיליון אלקטרוני, מסמך, מצגת או טופס שיש לו הרשאת עריכה בהם. (הטריגר לא פועל כשמגיבים לטופס, אלא רק כשפותחים את הטופס כדי לערוך אותו). השימוש הנפוץ ביותר ב-onOpen(e) הוא להוספת פריטי תפריט מותאמים אישית ל-Google Sheets,‏ Slides,‏ Docs או Forms.

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

הטריגר onInstall(e) פועל באופן אוטומטי כשמשתמש מתקין תוסף לעריכה מתוך Google Docs,‏ Sheets,‏ Slides או Forms. הטריגר לא יפעל כשמשתמש מתקין את התוסף מהאתר Google Workspace Marketplace. חשוב לזכור שיש הגבלות מסוימות על הפעולות שאפשר לבצע באמצעות onInstall(e). מידע נוסף זמין במאמר בנושא הרשאה. השימוש הנפוץ ביותר ב-onInstall(e) הוא פשוט להפעיל את onOpen(e) כדי להוסיף תפריטים מותאמים אישית. אחרי הכל, כשמתקינים תוסף, הקובץ כבר פתוח, ולכן onOpen(e) לא פועל בעצמו אלא אם פותחים את הקובץ מחדש.

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

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

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

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

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

בדוגמה הבאה, אם בוחרים תא ריק, הפונקציה onSelectionChange(e) מגדירה את הרקע של התא לאדום.

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) וגם doPost(e)

הטריגר doGet(e) פועל באופן אוטומטי כשמשתמש מבקר באפליקציית אינטרנט או כשתוכנית שולחת בקשת HTTP GET לאפליקציית אינטרנט. הטריגר doPost(e) פועל כשתוכנית שולחת בקשת HTTP POST לאפליקציית אינטרנט. אפשר למצוא הסברים נוספים על הטריגרים האלה במדריכים בנושא אפליקציות אינטרנט, שירות HTML ושירות תוכן. חשוב לדעת שהשדות doGet(e) ו-doPost(e) לא כפופים להגבלות שמפורטות למעלה.

סוגי הטריגרים הזמינים

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

אירוע	טריגרים פשוטים	טריגרים שניתן להתקין
פתיחה	function onOpen(e)
עריכה	function onEdit(e)
שינוי הבחירה	function onSelectionChange(e)
התקנה	function onInstall(e)
שינוי
שליחת טופס
מבוסס זמן (שעון)
קבל	function doGet(e)
פוסט	function doPost(e)

* האירוע 'פתיחה' ב-Google Forms לא מתרחש כשמשתמש פותח טופס כדי להשיב, אלא כשעריכה פותח את הטופס כדי לשנות אותו.