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

טריגרים מאפשרים ל-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 שניות.
  • בנסיבות מסוימות, תוספי עריכה מריצים את onOpen(e) ו-onEdit(e) טריגרים פשוטים במצב 'ללא הרשאה', סיבוכים נוספים. מידע נוסף זמין במאמר מדריך למחזור החיים של ההרשאות לתוסף.
  • טריגרים פשוטים כפופים לטריגר של Apps Script מכסות המכסה.

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

onOpen(e)

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

triggers/triggers.gs
/**
 * 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
/**
 * 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
/**
 * 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) מגדירה את התא לאדום.

triggers/triggers.gs
/**
 * 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 יש תמיכה ב-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
Forms
Docs
מיקום מודעה עצמאי
קבל
מיקום מודעה עצמאי

function doGet(e)
פוסט
מיקום מודעה עצמאי

function doPost(e)

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