טריגרים ניתנים להתקנה

בדומה לטריגרים פשוטים, טריגרים שניתנים להתקנה מאפשרים ל-Google Apps Script להפעיל פונקציה באופן אוטומטי כשמתרחש אירוע מסוים, כמו פתיחת מסמך. עם זאת, טריגרים שניתנים להתקנה מציעים גמישות רבה יותר מטריגרים פשוטים: הם יכולים להפעיל שירותים שנדרש עבורם אישור, הם מציעים כמה סוגים נוספים של אירועים, כולל טריגרים מבוססי-זמן (שעון), ואפשר לשלוט בהם באופן פרוגרמטי. גם בטריגרים פשוטים וגם בטריגרים שניתן להתקין,‏ Apps Script מעביר לפונקציה שהופעלה אובייקט אירוע שמכיל מידע על ההקשר שבו האירוע התרחש.

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

הגבלות

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

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

• הפעלות של סקריפטים ובקשות API לא גורמות להפעלת טריגרים. לדוגמה, התקשרות אל FormResponse.submit() כדי לשלוח תשובה חדשה לטופס לא גורמת להפעלת טריגר השליחה של הטופס.

  חריג להגבלה הזו הוא Form.submitGrades(). אם הקוד שלכם משתמש בטריגר onFormSubmit, הפעלת הטריגר Form.submitGrades() מפעילה את התנאי onFormSubmit וגורמת ללולאה אינסופית. כדי למנוע לולאה אינסופית, מוסיפים קוד שבודק אם הציונים כבר קיימים לפני שמבצעים קריאה ל-submitGrades().

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

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

• טריגרים שניתן להתקין כפופים למגבלות המכסה של טריגרים ב-Apps Script.

טריגרים שמבוססים על זמן

טריגר שמבוסס על זמן (נקרא גם טריגר שעון) דומה למשימת cron ב-Unix. טריגרים מבוססי-זמן מאפשרים להריץ סקריפטים בזמן מסוים או במרווח חוזר, בתדירות של פעם בדקה או פעם בחודש. (תוסף יכול להשתמש בטריגר מבוסס-זמן פעם בשעה לכל היותר). יכול להיות שהשעה תהיה אקראית מעט – לדוגמה, אם יוצרים טריגר חוזר לשעה 9:00, Apps Script בוחר שעה בין 9:00 ל-10:00, ואז שומר על התזמון הזה באופן עקבי מיום ליום, כך שחולפות 24 שעות לפני שהטריגר מופעל שוב.

טריגרים מבוססי-אירועים

טריגרים מבוססי-אירועים שניתנים להתקנה דומים מבחינה רעיונית לטריגרים פשוטים כמו onOpen(), אבל הם יכולים להגיב לאירועים נוספים, וההתנהגות שלהם שונה.

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

יש כמה טריגרים שניתן להתקין באפליקציות של Google Workspace:

• טריגר open שניתן להתקנה מופעל כשמשתמש פותח גיליון אלקטרוני, מסמך או טופס שיש לו הרשאה לערוך.
• טריגר edit שניתן להתקנה מופעל כשמשתמש משנה ערך בגיליון אלקטרוני.
• טריגר שינוי שניתן להתקנה מופעל כשמשתמש משנה את המבנה של גיליון אלקטרוני – למשל, כשמוסיפים גיליון חדש או מסירים עמודה.
• טריגר form submit שניתן להתקנה מופעל כשמשתמש מגיב לטופס. יש שתי גרסאות של הטריגר form-submit, אחת ל-Google Forms עצמו ואחת ל-Sheets אם הטופס נשלח לגיליון אלקטרוני.
• טריגר אירוע ביומן שניתן להתקנה מופעל כשאירועים ביומן של משתמש מתעדכנים – נוצרים, נערכים או נמחקים.

טריגרים שאפשר להתקין זמינים בסקריפטים עצמאיים ובסקריפטים מקושרים. לדוגמה, סקריפט עצמאי יכול ליצור באופן פרוגרמטי טריגר שניתן להתקנה עבור קובץ שרירותי של Google Sheets על ידי קריאה ל-TriggerBuilder.forSpreadsheet(key) והעברת מזהה הגיליון האלקטרוני.

ניהול ידני של טריגרים

כדי ליצור ידנית טריגר שניתן להתקנה בכלי לעריכת סקריפטים:

1. פותחים את פרויקט Apps Script.
2. בצד ימין, לוחצים על מפעילים alarm.
3. בפינה השמאלית התחתונה, לוחצים על הוספת טריגר.
4. בוחרים את סוג הטריגר שרוצים ליצור ומגדירים אותו.
5. לוחצים על שמירה.

ניהול טריגרים באופן פרוגרמטי

אפשר ליצור ולמחוק טריגרים באופן פרוגרמטי באמצעות שירות הסקריפט. מתחילים בשיחה עם ScriptApp.newTrigger(functionName), שמחזירה TriggerBuilder.

בדוגמה הבאה מוצגות שתי הפעלות שמבוססות על זמן – אחת שמופעלת כל 6 שעות, ואחת שמופעלת כל יום שני בשעה 9:00 (באזור הזמן שהוגדר בסקריפט).

/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger("myFunction").timeBased().everyHours(6).create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger("myFunction")
    .timeBased()
    .onWeekDay(ScriptApp.WeekDay.MONDAY)
    .atHour(9)
    .create();
}

בדוגמה הבאה מוצג אופן היצירה של טריגר פתוח שאפשר להתקין בגיליון אלקטרוני. בניגוד לonOpen()טריגר פשוט, הסקריפט של הטריגר שניתן להתקנה לא צריך להיות מקושר לגיליון האלקטרוני. כדי ליצור את הטריגר הזה מסקריפט עצמאי, מחליפים את SpreadsheetApp.getActive() בקריאה ל-SpreadsheetApp.openById(id).

/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger("myFunction").forSpreadsheet(ss).onOpen().create();
}

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

/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

לפני שיוצרים טריגר, צריך לוודא שלפונקציה המשויכת יש את כל הרשאות ה-OAuth הנדרשות.

שגיאות בטריגרים

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

במקום זאת, Apps Script שולח אימייל כמו זה:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

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

כדי לפתור שגיאות בסקריפט, לוחצים על הקישור בהודעת האימייל כדי לפתוח את פרויקט הסקריפט. אחרי שפותחים את הפרויקט, לוחצים על Executions playlist_play בחלונית הניווט הימנית כדי לראות את יומני הביצוע. ביומנים אפשר לראות אילו הרצות נכשלו, והם כוללים הודעות שגיאה שיעזרו לכם לאבחן ולפתור את הבעיה.

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

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

1. עוברים אל script.google.com.
2. בצד ימין, לוחצים על המפעילים שלי.
3. כדי למחוק טריגר, משמאל לטריגר, לוחצים על סמל האפשרויות הנוספות more_vert > מחיקת הטריגר.

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

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

טריגרים בתוספים

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