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

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

הערה: רק תוספים של 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