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

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

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

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

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

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

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

מודל ההרשאות

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

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

תוספי עריכה בתפריט תוספים הם מותקנות, מופעלות או גם וגם.

• תוסף מותקן עבור חשבון מסוים משתמש אחרי שהוא או האדמין שלו מקבלים את ההודעה 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. לא פורסם תוספי עריכה פועלים עם onOpen() ב-AuthMode.LIMITED. אבל, לפעמים אפשר לבדוק תוסף עריכה כדי לוודא שתוסף בפיתוח פועל שמיועד לשימוש בכל מצב הרשאה.

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

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

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

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

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

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

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

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