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

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

מודל ההרשאות של תוספי עריכה הוא מורכב יותר מכמה סיבות:

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

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

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

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

מודל הרשאה

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

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

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

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

ב-Apps Script, מצב ההרשאה הוא המאפיין authMode של פרמטר האירוע של Apps Script, e. הערך של e.authMode תואם לערך קבוע במדד Apps Script ScriptApp.AuthMode.

מצבי הרשאה חלים על כל שיטות הביצוע של 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	שירותים שלא מקבלים גישה לנתוני משתמשים	שירותים שלא מקבלים גישה לנתוני משתמשים	כל השירותים

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

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

5. שומרים את הקוד ויוצרים פריסה לבדיקה.

   כשיוצרים פריסה לבדיקה, חשוב לוודא שהשדה Config הוא Installed for current user (התקנה לגבי המשתמש הנוכחי) ושהטקסט מתחת לתיבה Config (הגדרות אישיות) הוא Check in AuthMode.None (בדיקה ב-AuthMode.None)

6. מפעילים את הפריסה לבדיקה ופותחים את התפריט תוספים.

7. אם כל המנות בתפריט מוצגות, הבעיה נפתרה. אם מוצג רק תפריט העזרה, חוזרים לשלב 1. ייתכן שפספסת שיחת שירות.

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

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