תהליך ההרשאה להרבה אפליקציות המבוססות על Apps Script הוא פשוט כי פרויקט סקריפט מבקש את ההרשאות החסרות הדרושות לו כשמישהו מנסה כדי להשתמש בו.
מודל ההרשאה עבור תוספי עריכה הם מורכב יותר מכמה סיבות:
כשמשתמש יוצר קובץ, כל התוספים שהמשתמש מתקין מופיעים בתפריט תוספים, אפילו אם המשתמש עדיין לא אישר את התוספים האלה.
התוספים האלה פועלים על קבצים ב- Google Drive שניתן לשתף עם שותפי עריכה. שותפי עריכה שלא להתקין את תוסף העריכה. הם מופיעים במסמכים שבו יוצר הקובץ השתמש בו.
תוספי עריכה מריצים באופן אוטומטי את
onOpen()
שלהם פועל כשמסמך נפתח.
כדי להגן על נתוני המשתמשים, הופעלו מצבי הרשאה שהופכים שירותים מסוימים
לא זמין אצל onOpen()
. המדריך הזה יכול לעזור לכם להבין מה הקוד
לעשות ומתי.
מודל ההרשאות
מצב ההרשאה של תוסף עריכה תלוי ב- המצב שלה, שתלוי במי שמשתמש בו: המשתמש שהתקין את התוסף או שותף עריכה.
מצבים של תוספי עריכה
תוספי עריכה בתפריט תוספים הם מותקנות, מופעלות או גם וגם.
- תוסף מותקן עבור חשבון מסוים משתמש אחרי שהוא או האדמין שלו מקבלים את ההודעה 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
תואם קבוע ב-Apps Script
enum ScriptApp.AuthMode
.
מצבי ההרשאה חלים על כל שיטות הביצוע של Apps Script.
כולל הרצה מעורך הסקריפטים, מפריט בתפריט או מ-Apps Script
google.script.run
. אבל, לפעמים
אפשר לבדוק את המאפיין 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()
. אם משתמש לוחץ
האפשרות תוספים בתפריט פועלת.
תוסף העריכה מותקן
כשמותקן תוסף עריכה מהחנות,
הפונקציה onInstall()
רצה בטווח AuthMode.FULL
. במצב ההרשאה הזה, הפונקציה
יכול להריץ תהליך הגדרה מורכב. כדאי לך גם
להשתמש ב-onInstall()
כדי ליצור אפשרויות בתפריט, מכיוון שהמסמך, הטופס, המצגת
או שהגיליון האלקטרוני כבר פתוח והפונקציה onOpen()
לא פעלה.
הדוגמה הבאה מראה איך לקרוא לפונקציה onOpen()
מהפונקציה onInstall()
:
function onInstall(e) {
onOpen(e);
// Perform additional setup as needed.
}
תוסף העריכה פתוח
כשמסמך, טופס, מצגת או גיליון אלקטרוני נפתחים, הם נטענים
תוסף עריכה שהמשתמש הנוכחי התקין, או
שכל שותף עריכה הפעיל בקובץ, וקורא
בכל אחת מפונקציות ה-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()
. בנוסף, צריך לאתר ולהסיר כל שירות שלא שייך לפונקציה. - זיהוי פונקציות שיכולות להכיל את שורות הקוד שהגיבו או הוסרו בשלב הקודם, במיוחד אלה שמשתמשים במידע שהם מייצרים, ולהעביר את קריאות השירות לפונקציות שצריכות אותן. סידור מחדש או שכתוב ב-codebase כדי לכלול את השינויים שבוצעו בשלבים הקודמים.
שומרים את הקוד ויוצרים פריסה לבדיקה.
כשיוצרים פריסת בדיקה, צריך לוודא שהשדה Config (הגדרה) היא מותקן למשתמש הנוכחי, ושהטקסט שמתחת לתיבת ההגדרה מציין בדיקה ב
AuthMode.None
מפעילים את הפריסה לבדיקה ופותחים את התפריט תוספים.
אם כל האפשרויות בתפריט מוצגות, הבעיה נפתרה. אם מוצג רק התפריט עזרה, חוזרים לשלב 1. יכול להיות שפספסת שיחת שירות.