ההרשאה לשימוש בהרבה אפליקציות שמבוססות על Apps Script היא פשוטה, כי פרויקט הסקריפט מבקש את כל ההרשאות החסרות שהוא צריך כשמישהו מנסה להשתמש בו.
מודל ההרשאות של תוספים לעורך מורכב יותר מכמה סיבות:
כשמשתמש יוצר קובץ, כל התוספים שהוא מתקין מופיעים בתפריט תוספים, גם אם הוא עדיין לא אישר את השימוש בהם.
התוספים האלה פועלים בקבצים ב-Google Drive שאפשר לשתף עם שותפי עריכה. שותפי עריכה שלא התקינו את התוסף Editor רואים אותו במסמכים שבהם יוצר הקובץ השתמש בו.
תוספים של Editor מריצים באופן אוטומטי את הפונקציות שלהם כשפותחים מסמך.
onOpen()
כדי להגן על נתוני המשתמשים, מוחלים מצבי הרשאה שגורמים לכך ששירותים מסוימים לא יהיו זמינים ל-onOpen()
. המדריך הזה יעזור לכם להבין מה הקוד יכול לעשות ומתי.
מודל ההרשאות
מצב ההרשאה של תוסף Editor תלוי במצב שלו, שמשתנה בהתאם למי שמשתמש בו: המשתמש שהתקין את התוסף או משתף פעולה.
מצבים של תוסף עריכה
תוספים של Editor בתפריט תוספים מותקנים, מופעלים או גם וגם.
- תוסף מותקן עבור משתמש מסוים אחרי שהוא או האדמין שלו מורידים אותו מ-Google Workspace Marketplace ומאשרים לו גישה לנתונים שלהם ב-Google.
- תוסף מופעל במסמך, בטופס, במצגת או בגיליון אלקטרוני כשמישהו משתמש בו שם.
- כשמשתפים פעולה בקובץ ואחד מהמשתמשים משתמש בתוסף, התוסף מותקן עבור המשתמש הזה ומופעל עבור הקובץ.
בטבלה הבאה מסוכמים ההבדלים בין 'מותקן' לבין 'מופעל'. הערה: כשבודקים סקריפט כתוסף, אפשר להריץ את הבדיקה באחד מהמצבים האלה או בשניהם.
מותקן | מופעל | |
---|---|---|
חל על | משתמש | מסמך, טופס, מצגת או גיליון אלקטרוני |
גורם השגיאה | הורדת תוסף מהחנות | הורדת תוסף מהחנות בזמן השימוש במסמך, בטופס, במצגת או בגיליון האלקטרוני, או שימוש בתוסף שהותקן בעבר במסמך, בטופס, במצגת או בגיליון האלקטרוני |
התפריט גלוי ל | רק המשתמש הזה, בכל המסמכים, הטפסים, המצגות או הגיליונות האלקטרוניים שהוא פותח או יוצר | כל שותפי העריכה במסמך, בטופס, במצגת או בגיליון האלקטרוני |
מצב ההרשאה של onOpen() |
AuthMode.NONE (אלא אם היא גם מופעלת, ואז AuthMode.LIMITED) |
AuthMode.LIMITED |
מצבי הרשאה
הפונקציה onOpen()
של תוסף Editor פועלת אוטומטית כשמשתמש פותח מסמך, טופס, מצגת או גיליון אלקטרוני.
כדי להגן על נתוני המשתמשים, Apps Script מגביל את הפעולות שאפשר לבצע באמצעות הפונקציה onOpen()
. מצב התוסף של העורך קובע באיזה מצב הרשאה הפונקציה onOpen()
פועלת.
אם תוסף של כלי העריכה מופעל בקובץ, בטופס, במצגת או בגיליון האלקטרוני, הפונקציה onOpen()
פועלת ב-AuthMode.LIMITED
. אם התוסף לא מופעל ורק מותקן, onOpen()
פועל ב-AuthMode.NONE
.
ב-AuthMode.NONE
, תוסף לא יכול להפעיל שירותים מסוימים עד שהמשתמש יוצר אינטראקציה עם התוסף על ידי לחיצה או הפעלה של פונקציות מותאמות אישית. אם התוסף מנסה להשתמש בשירותים האלה בהיקף onOpen()
, onInstall()
או בהיקף גלובלי, ההרשאות לא יפעלו ושיחות אחרות, כמו מילוי תפריטים, ייפסקו. האפשרות היחידה שנתמכת היא עזרה.
כדי להריץ קריאות מוגבלות לשירות, צריך להשתמש במצב ההרשאה AuthMode.FULL
. פונקציות של אינטראקציות עם המשתמש, כמו לחיצה על אפשרות בתפריט, פועלות רק במצב הזה. אחרי שהקוד מופעל במצב AuthMode.FULL
, התוסף יכול להשתמש בכל ההיקפים שהמשתמש אישר.
Apps Script מעביר את מצב ההרשאה כמאפיין authMode
של פרמטר האירוע של Apps Script, e
; הערך של e.authMode
תואם לקבוע ב-enum ScriptApp.AuthMode
של Apps Script.
מצבי ההרשאה חלים על כל שיטות ההפעלה של Apps Script,
כולל הפעלה מכלי העריכה של הסקריפט, מפריט בתפריט או מקריאה של google.script.run
Apps Script. עם זאת,
אפשר לבדוק את המאפיין e.authMode
רק אם הסקריפט מופעל כתוצאה של טריגר כמו onOpen()
, onEdit()
או onInstall()
. פונקציות מותאמות אישית ב-Google Sheets משתמשות במצב הרשאה משלהן, AuthMode.CUSTOM_FUNCTION
, שדומה ל-LIMITED
אבל יש בו הגבלות שונות במקצת. בכל המקרים האחרים, הסקריפטים פועלים ב-AuthMode.FULL
, כפי שמתואר בטבלה הבאה.
NONE |
LIMITED |
CUSTOM_FUNCTION |
FULL |
|
---|---|---|---|---|
מתרחש למשך | onOpen() (אם המשתמש התקין תוסף אבל לא הפעיל אותו במסמך, בטופס, במצגת או בגיליון האלקטרוני) |
onOpen() (בכל שאר הפעמים)onEdit() (רק ב-Sheets) |
פונקציות בהתאמה אישית | בכל שאר הזמנים, כולל: טריגרים שאפשר להתקין onInstall() google.script.run |
גישה לנתוני משתמשים | לוקאל בלבד | לוקאל בלבד | לוקאל בלבד | כן |
גישה למסמך, לטופס, למצגת או לגיליון אלקטרוני | לא | כן | כן – קריאה בלבד | כן |
גישה לממשק המשתמש | הוספת פריטים לתפריט | הוספת פריטים לתפריט | לא | כן |
גישה אל Properties |
לא | כן | כן | כן |
גישה אל Jdbc , UrlFetch |
לא | לא | כן | כן |
שירותים אחרים | Logger Utilities |
כל השירותים שלא ניגשים לנתוני משתמשים | כל השירותים שלא ניגשים לנתוני משתמשים | כל השירותים |
מחזור החיים של הרשאות בתוסף עריכה
כשמתקינים תוסף עבור המשתמש הנוכחי או מפעילים אותו בקובץ הנוכחי, התוסף נטען במסמך, בטופס, במצגת או בגיליון האלקטרוני כשפותחים את הקובץ. התוסף מופיע בתפריט תוספים ומתחיל להאזין לטריגרים פשוטים onInstall()
, onOpen()
ו-onEdit()
. אם משתמש לוחץ על פריט בתפריט תוספים, הוא מופעל.
התוסף של Editor מותקן
כשמתקינים תוסף של Editor מהחנות, הפונקציה onInstall()
שלו פועלת ב-AuthMode.FULL
. במצב ההרשאה הזה, התוסף יכול להריץ תהליך הגדרה מורכב. מומלץ גם להשתמש ב-onInstall()
כדי ליצור פריטים בתפריט, כי המסמך, הטופס, המצגת או הגיליון האלקטרוני כבר פתוחים והפונקציה onOpen()
לא הופעלה.
בדוגמה הבאה אפשר לראות איך מפעילים את הפונקציה onOpen()
מתוך הפונקציה onInstall()
:
function onInstall(e) {
onOpen(e);
// Perform additional setup as needed.
}
התוסף Editor נפתח
כשפותחים מסמך, טופס, מצגת או גיליון אלקטרוני, כל תוסף של Editor שהמשתמש הנוכחי התקין או שמשתף פעולה כלשהו הפעיל בקובץ נטען, וכל אחת מהפונקציות onOpen()
שלו מופעלת. מצב ההרשאה שבו onOpen()
התוסף פועל תלוי בשאלה אם הוא מותקן או מופעל.
אם התוסף יוצר רק תפריט בסיסי, המצב לא משנה. בדוגמה הבאה מוצגת פונקציית onOpen()
בסיסית:
function onOpen(e) {
SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
.addItem('Insert chart', 'insertChart')
.addItem('Update charts', 'updateCharts')
.addToUi();
}
כדי להוסיף פריטים דינמיים לתפריט על סמך מאפיינים של Apps Script שמאוחסנים, לקרוא את התוכן של הקובץ הנוכחי או לבצע משימות מתקדמות אחרות, צריך לזהות את מצב ההרשאה ולטפל בו בצורה מתאימה.
בדוגמה הבאה מוצגת פונקציה מתקדמת של onOpen()
שמשנה את הפעולה שלה בהתאם למצב ההרשאה:
function onOpen(e) {
var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
if (e && e.authMode == ScriptApp.AuthMode.NONE) {
// Add a normal menu item (works in all authorization modes).
menu.addItem('Start workflow', 'startWorkflow');
} else {
// Add a menu item based on properties (doesn't work in AuthMode.NONE).
var properties = PropertiesService.getDocumentProperties();
var workflowStarted = properties.getProperty('workflowStarted');
if (workflowStarted) {
menu.addItem('Check workflow status', 'checkWorkflow');
} else {
menu.addItem('Start workflow', 'startWorkflow');
}
}
menu.addToUi();
}
חשוב לזכור שתוספים לא יכולים לפתוח סרגלי צד או תיבות דו-שיח בזמן שהם פועלים ב-AuthMode.LIMITED
. אפשר להשתמש בפריטי תפריט כדי לפתוח סרגלי צד וחלונות דו-שיח, כי הם פועלים ב-AuthMode.FULL
.
משתמש מפעיל את התוסף לעריכה
כשמשתמש לוחץ על פריט בתפריט תוספים, מערכת Apps Script בודקת קודם אם המשתמש התקין את התוסף, ואם לא, היא מציעה לו לעשות זאת. אם המשתמש אישר את התוסף, הסקריפט מריץ את הפונקציה שמתאימה לפריט בתפריט ב-AuthMode.FULL
. אם התוסף לא הופעל כבר, הוא יופעל במסמך, בטופס, במצגת או בגיליון האלקטרוני.
פתרון בעיות שמונעות עיבוד של תפריטים של תוספים
יכול להיות שתפריט התוסף לא יוצג אם הקוד לא מנהל את מצבי ההרשאה בצורה נכונה. לדוגמה:
תוסף מנסה להריץ שירות Apps Script שלא נתמך במצב ההרשאה הנוכחי.
תוסף מנסה להפעיל קריאה לשירות לפני שהמשתמש יוצר איתו אינטראקציה.
כדי להסיר או לסדר מחדש קריאה לשירות שגורמת לשגיאות הרשאה ב-AuthMode.NONE
, אפשר לנסות את הפעולות הבאות:
- פותחים את פרויקט Apps Script של התוסף ומאתרים את הפונקציה
onOpen()
. - מחפשים בפונקציה
onOpen()
אזכורים של שירותים או אובייקטים של Apps Script שמשויכים אליהם, כמוPropertiesService
,SpreadsheetApp
אוGmailApp
. - אם נעשה שימוש בשירות למטרה אחרת מלבד יצירת רכיבי ממשק המשתמש, צריך להסיר אותו או להוסיף אותו לבלוק של הערות.
משאירים רק את אמצעי התשלום האלה:
.getUi()
,.createMenu()
,.addItem()
ו-.addToUi()
. בנוסף, אפשר למצוא ולהסיר כל שירות שלא נמצא בתוך פונקציה. - מזהים פונקציות שעשויות להכיל את שורות הקוד שהוסרו או שהוסף להן הערה בשלב הקודם, במיוחד פונקציות שמשתמשות במידע שהן מייצרות, ומעבירים את הקריאות לשירות לפונקציות שזקוקות להן. מסדרים מחדש או כותבים מחדש את בסיס הקוד כדי להתאים לשינויים שבוצעו בשלבים הקודמים.
שומרים את הקוד ויוצרים פריסת בדיקה.
כשיוצרים פריסת בדיקה, מוודאים שהשדה Config הוא Installed for current user ושהטקסט שמתחת לתיבה Config הוא Test in
AuthMode.None
.מפעילים את פריסת הבדיקה ופותחים את התפריט תוספים.
אם כל הפריטים בתפריט מוצגים, הבעיה נפתרה. אם מופיע רק התפריט עזרה, חוזרים לשלב 1. יכול להיות שהחמצתם שיחה משירות הלקוחות.