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

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

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

איך מתחילים

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

• 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 שניות.
• בנסיבות מסוימות, תוספים של עורכים מריצים את הטריגרים הפשוטים של 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) פועל באופן אוטומטי כשמשתמש מתקין תוסף עריכה מתוך 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
מבוסס-זמן (שעון)		Sheets Slides טפסים Docs דף עצמאי
הורדה	מיקום מודעה עצמאי function doGet(e)
פוסט	מיקום מודעה עצמאי function doPost(e)

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