טריגרים לתוספי עריכה

טריגרים של Apps Script גורמים להפעלה של פונקציית סקריפט מסוימת (פונקציית הטריגר) בכל פעם שאירוע מסוים מתרחש. רק אירועים מסוימים יכולים לגרום להפעלה של טריגרים, וכל אפליקציה של Google Workspace תומכת בקבוצה שונה של אירועים.

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

אחרי שיוצרים את אובייקט האירוע, Apps Script מעביר אותו כפרמטר לפונקציית הטריגר. פונקציית הטריגר היא פונקציית קריאה חוזרת (callback) שאתם צריכים להטמיע בעצמכם, כדי לבצע את הפעולות המתאימות בתגובה לאירוע. לדוגמה, בתוסף ל-Editor, הטריגר משמש ליצירת פריטים בתפריט של התוסף כשמסמך נפתח. במקרה כזה, מטמיעים את פונקציית הטריגר onOpen(e) כדי ליצור את הפריטים בתפריט שנחוצים לתוסף, אולי באמצעות הנתונים באובייקט האירוע.

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

סוגי טריגרים של תוסף עריכה

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

בטבלה הבאה מפורטים סוגי הטריגרים הפשוטים והמתקינים שאפשר להשתמש בהם בתוספים ל-Editor, וכן קישורים לאובייקטי האירועים המתאימים:

אירוע	אובייקט אירוע	טריגרים פשוטים	טריגרים שניתן להתקין
פתיחה קובץ העורכים נפתח.	אובייקט האירוע onOpen ב-Docs אובייקט האירוע onOpen ב-Forms אובייקט האירוע onOpen ב-Sheets אובייקט האירוע onOpen ב-Slides	Docs Forms* Sheets Slides function onOpen(e)	Docs Forms Sheets
התקנה התוסף מותקן.	אובייקט האירוע onInstall	Docs Forms Sheets Slides function onInstall(e)
עריכה התוכן של תא בגיליון האלקטרוני משתנה.	אירוע onEdit של Sheets	Sheets function onEdit(e)	Sheets
שינוי התוכן בגיליון עובר עריכה או עיצוב.	אירוע onChange של Sheets		Sheets
Form-submit הטופס ב-Google Forms נשלח.	אובייקט אירוע של שליחת טופס ב-Forms אובייקט אירוע של שליחת טופס ב-Sheets		Forms Sheets
מבוסס-זמן (שעון) הטריגר מופעל במועד או במרווח זמן ספציפיים.	אובייקט אירוע מבוסס-זמן		Docs Forms Sheets Slides

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

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

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

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

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

הגבלות

טריגרים פשוטים בתוספים כפופים לאותן הגבלות שחלות על טריגרים פשוטים בסוגים אחרים של פרויקטים ב-Apps Script. חשוב לשים לב במיוחד להגבלות הבאות כשאתם מתכננים תוספים:

• טריגרים פשוטים לא פועלים אם הקובץ נפתח במצב קריאה בלבד (לצפייה או להוספת תגובה). ההתנהגות הזו מונעת את האכלוס של תפריטי התוספים.
• בנסיבות מסוימות, תוספים ל-Editor מפעילים את הטריגרים הפשוטים onOpen(e) ו-onEdit(e) במצב ללא הרשאה. במצב הזה יש כמה סיבוכים נוספים, כפי שמתואר במודל ההרשאה של התוספים.
• טריגרים פשוטים לא יכולים להשתמש בשירותים או לבצע פעולות אחרות שדורשות הרשאה, מלבד מה שמתואר במודל ההרשאה של התוסף.
• טריגרים פשוטים לא יכולים לפעול למשך יותר מ-30 שניות. חשוב לצמצם את כמות העיבוד שמתבצע בפונקציית טריגר פשוטה.
• טריגרים פשוטים כפופים למכסות של טריגרים ב-Apps Script.

טריגרים שניתן להתקין בתוספים

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

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

תוספים יכולים להשתמש בטריגרים הניתנים להתקנה הבאים:

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

• טריגרים להתקנה מסוג Form-submit פועלים כשמתקבלת תשובה לטופס ב-Google Forms.

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

הרשאה לטריגרים שניתן להתקין

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

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

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

בהמשך מופיעה דוגמה למבנה המומלץ לשימוש בפונקציות טריגר כדי למנוע מלכודות הרשאה. פונקציית הטריגר לדוגמה מגיבה לאירוע שליחת טופס בתוסף ל-Google Sheets. אם נדרשת הרשאה מחדש, היא שולחת למשתמש התוסף התראה באימייל באמצעות תבנית HTML.

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

הגבלות

טריגרים שניתן להתקין בתוספים כפופים לאותן הגבלות שחלות על טריגרים שניתן להתקין בסוגי פרויקטים אחרים של Apps Script.

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

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