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

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

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

תחילת העבודה

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

• ‫onOpen(e) פועל כשמשתמש פותח גיליון אלקטרוני, מסמך, מצגת או טופס שיש לו הרשאה לערוך.
• ‫onInstall(e) מופעל כשמשתמש מתקין תוסף של עורכי Google מתוך 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.

triggers/triggers.gs

הצגת הקוד ב-GitHub

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

triggers/triggers.gs

הצגת הקוד ב-GitHub

/**
 * 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) שבהמשך מגדירה הערה בתא שמתעד את הפעם האחרונה שבה הוא נערך.

triggers/triggers.gs

הצגת הקוד ב-GitHub

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

הערה: הטריגר onEdit() יכול להוסיף לתור עד 2 אירועים של טריגר.

onSelectionChange(e)

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

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

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

triggers/triggers.gs

הצגת הקוד ב-GitHub

/**
 * 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 תומכים בטריגרים של פתיחה שאפשר להתקין.

אירוע	טריגרים פשוטים	טריגרים שאפשר להתקין
פתיחה	Sheets Slides Forms* Docs function onOpen(e)	Sheets Forms* Docs
עריכה	Sheets function onEdit(e)	Sheets
שינוי הבחירה	Sheets function onSelectionChange(e)
התקנה	Sheets Slides Forms Docs function onInstall(e)
שינוי		Sheets
שליחת טופס		Sheets Forms
Time-driven (clock)		Sheets Slides Forms Docs Standalone
קבל	Standalone function doGet(e)
פוסט	Standalone function doPost(e)

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