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

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

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

תחילת העבודה

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

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

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

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)
שינוי
שליחת טופס
Time-driven (clock)
קבל	function doGet(e)
פרסום	function doPost(e)

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