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

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

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

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

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

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

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

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

בטבלה הבאה מפורטים סוגי הטריגרים הפשוטים והטריגרים שניתן להתקין שבהם תוספים ל-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 נשלח.	אובייקט האירוע form-submit ב-Forms אובייקט האירוע form-submit ב-Sheets		Forms Sheets
מופעל לפי זמן (שעון) הטריגר מופעל בזמן או במרווח זמן מוגדרים.	אובייקט של אירוע מבוסס-זמן	Docs Forms Sheets Slides

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

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

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

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

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

הגבלות

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

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

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

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

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

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

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

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

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

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

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

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

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

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