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

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

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

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

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

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

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

הערה: בניגוד לתוספים של Editor, בשלב הזה אי אפשר להשתמש בטריגרים פשוטים או בטריגרים שניתנים להתקנה של Apps Script בתוספים של Google Workspace. במקום זאת, הם משתמשים בטריגרים שמיועדים במיוחד לתוספים ל-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 Forms נשלח.	אובייקט האירוע form-submit של Forms אובייקט האירוע form-submit של 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.

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

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

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

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

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

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

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

Code.gs

triggers/form/Code.gs

הצגת הקוד ב-GitHub

/**
 * 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.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html

הצגת הקוד ב-GitHub

<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.