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

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

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

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

• התוספים האלה פועלים בקבצים ב-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, התוסף יכול להשתמש בכל ההיקפים שהמשתמש אישר.

הערה: רק תוספים שפורסמו של Editor יכולים להיות ב-AuthMode.NONE. תוספים של Editor שלא פורסמו פועלים ב-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 נפתח

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