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

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

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

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

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

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

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

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

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

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