טריגרים של 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 |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
התקנה התוסף מותקן. |
אובייקט אירוע onInstall |
![]() ![]() ![]() ![]()
|
|
עריכה תוכן התא בגיליון האלקטרוני השתנה. |
Sheets onEdit event object (ב-Sheets לעריכת אובייקט של אירוע) |
![]()
|
![]() |
שינוי התוכן בגיליון נערך או מעוצב. |
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.
Code.gs
authorizationemail.html
הגבלות
טריגרים שאפשר להתקין בתוספים כפופים לאותם שינויים הגבלות שמנהלים טריגרים שאפשר להתקין בסוגים אחרים של פרויקטים של Apps Script.
בנוסף להגבלות האלה, חלות כמה הגבלות על תוכנות התקנה מפעילים בתוספים באופן ספציפי:
- לכל תוסף יכול להיות רק מפעיל אחד מכל סוג, לכל משתמש ולכל מסמך. למשל, בגיליון אלקטרוני נתון, למשתמש יכולה להיות אפשרות עריכה אחת בלבד למרות שלמשתמש יכול להיות גם טריגר מסוג שליחת טופס מבוסס-זמן באותו גיליון אלקטרוני. משתמש אחר עם גישה לאותו גיליון אלקטרוני יכול להיות קבוצה נפרדת של טריגרים.
- תוספים יכולים ליצור טריגרים רק לקובץ שבו נעשה שימוש בתוסף. כלומר, תוסף שנעשה בו שימוש במסמך Google Docs א' לא יכול ליצור טריגר לפעולה לעקוב כשמסמך Google Docs נפתח.
- טריגרים שמבוססים על זמן לא יכולים לפעול בתדירות גבוהה יותר מפעם בשעה.
- התוספים לא שולחים למשתמש אימייל באופן אוטומטי כשקוד מופעל על ידי בטריגר שניתן להתקנה גורם לחריגה. המפתח צריך לבדוק לטיפול במקרים של כשלים בטיפול עדין.
- טריגרים של תוספים מפסיקים לפעול בכל אחד מהמצבים הבאים:
- אם המשתמש הסיר את התוסף,
- אם התוסף מושבת במסמך (אם הוא מופעל מחדש, הטריגר) יהיה פעיל שוב), או
- אם המפתח מבטל את הפרסום של התוסף או שולח גרסה לא תקינה אל חנות לתוספים.
- הפונקציות של טריגר התוספים מופעלות עד שהן מגיעות לקוד שמשתמש שירות לא מורשה, ובשלב זה הוא יפסיק. הדבר נכון רק אם התוסף מתפרסם, את אותו טריגר בפרויקט Apps Script רגיל, תוספים שלא פורסמו לא יופעלו בכלל אם נדרש חלק כלשהו בסקריפט אישור.
- טריגרים שאפשר להתקין כפופים לטריגר של Apps Script מכסות המכסה.