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

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

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

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

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

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

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

מודל הרשאות

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

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

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

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

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

מצבי הרשאה

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

אם תוסף של Editor מופעל בקובץ, בטופס, במצגת או בגיליון האלקטרוני, 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, כולל הפעלה מהכלי לעריכת סקריפטים, מאפשרות בתפריט או מקריאה ל-Apps Script google.script.run. עם זאת, אפשר לבדוק את המאפיין e.authMode רק אם הסקריפט מופעל כתוצאה של טריגר כמו onOpen, onEdit או onInstall. פונקציות מותאמות אישית ב-Google Sheets משתמשות במצב הרשאה משלהן, AuthMode.CUSTOM_FUNCTION, שדומה ל-LIMITED אבל יש בו הגבלות שונות במקצת. בכל המקרים האחרים, הסקריפטים פועלים ב-AuthMode.FULL, כפי שמתואר בטבלה הבאה.

מחזור החיים של הרשאות בתוסף לעורכים

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