טריגרים לתוספים של Editor

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הגבלות

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Code.gs

טריגרים/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

טריגרים/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.