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

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

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

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

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

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

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

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

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

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

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

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

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

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

הגבלות

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

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

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

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

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

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

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

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