הרשאה לתוסף עריכה

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

מודל ההרשאות של תוספים ל-Editor מורכב יותר מכמה סיבות:

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

• התוספים האלה פועלים בקבצים ב-Google Drive שאפשר לשתף עם שותפי עריכה. שותפי עריכה שלא התקינו את התוסף Editor רואים אותו במסמכים שבהם יוצר הקובץ השתמש בו.

• תוספים של Editor מריצים אוטומטית את הפונקציות onOpenשלהם כשמסמך נפתח.

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

מודל ההרשאות

מצב ההרשאה של תוסף Editor תלוי במצב שלו, שמשתנה בהתאם למי שמשתמש בו: המשתמש שהתקין את התוסף או משתף פעולה.

מצבים של תוסף עריכה

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

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

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

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

מצבי הרשאה

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

אם תוסף של Editor מופעל בקובץ, בטופס, במצגת או בגיליון האלקטרוני, onOpen פועל ב-AuthMode.LIMITED. אם התוסף לא מופעל ורק מותקן,‏ onOpen פועל ב-AuthMode.NONE.

ב-AuthMode.NONE, תוסף לא יכול להפעיל שירותים מסוימים עד שהמשתמש יוצר אינטראקציה עם התוסף על ידי לחיצה או הפעלה של פונקציות מותאמות אישית. אם התוסף מנסה להשתמש בשירותים האלה בהיקף onOpen, ‏onInstall או בהיקף גלובלי, ההרשאות לא יפעלו ושיחות אחרות, כמו מילוי תפריטים, ייפסקו. האפשרות היחידה שנתמכת היא עזרה.

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

רק תוספים שפורסמו של כלי העריכה יכולים להיות ב-AuthMode.NONE. תוספים שלא פורסמו של כלי העריכה פועלים ב-onOpen ב-AuthMode.LIMITED. עם זאת, מיועד באחד ממצבי ההרשאה. כדי לעשות את זה, צריך לבדוק תוסף ל-Editor.

‫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 שהמשתמש הנוכחי התקין או שמשתף פעולה כלשהו הפעיל בקובץ נטען, וכל אחת מהפונקציות 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();
}

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

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

משתמש מפעיל את התוסף לעריכה

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

פתרון בעיות שמונעות עיבוד של תפריטי תוספים

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

• תוסף מנסה להריץ שירות של Apps Script שלא נתמך במצב ההרשאה הנוכחי.

• תוסף מנסה להפעיל קריאה לשירות לפני שהמשתמש יוצר איתו אינטראקציה.

כדי להסיר או לסדר מחדש קריאה לשירות שגורמת לשגיאות הרשאה ב-AuthMode.NONE, אפשר לנסות את הפעולות הבאות:

1. פותחים את פרויקט Apps Script של התוסף ומאתרים את הפונקציה onOpen.
2. מחפשים בפונקציה onOpen אזכורים של שירותים או אובייקטים של Apps Script שמשויכים אליהם, כמו PropertiesService, SpreadsheetApp או GmailApp.
3. אם משתמשים בשירות למטרה אחרת מלבד יצירת רכיבי ממשק המשתמש, צריך להסיר אותו או להוסיף אותו לבלוק של הערות. משאירים רק את אמצעי התשלום האלה: .getUi,‏ .createMenu,‏ .addItem ו-.addToUi. בנוסף, אפשר למצוא ולהסיר כל שירות שנמצא מחוץ לפונקציה.
4. מזהים פונקציות שעשויות להכיל את שורות הקוד שהוסרו או שהפכו להערות בשלב הקודם, במיוחד פונקציות שמשתמשות במידע שהן יוצרות, ומעבירים את הקריאות לשירות לפונקציות שזקוקות להן. מסדרים מחדש את בסיס הקוד או כותבים אותו מחדש כדי להתאים לשינויים שבוצעו בשלבים הקודמים.
5. שומרים את הקוד ויוצרים פריסת בדיקה. כשיוצרים פריסת בדיקה, מוודאים שהשדה Config הוא Installed for current user ושהטקסט שמתחת לתיבה Config הוא Test in AuthMode.NONE.
6. מפעילים את פריסת הבדיקה ופותחים את התפריט תוספים.
7. אם כל הפריטים בתפריט מוצגים, הבעיה נפתרה. אם מופיע רק התפריט עזרה, חוזרים לשלב 1. יכול להיות שהחמצתם שיחה משירות הלקוחות.

נושאים קשורים

• אפליקציות אינטרנט
• סוגי תוספים
• בדיקת תוסף של Editor