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

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

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

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

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

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

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

מודל הרשאה

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

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

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

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

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

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

מצבי הרשאה

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

אם התוסף של עורך מופעל בקובץ, בטופס, במצגת או בגיליון האלקטרוני, הפקודה onOpen() תרוץ ב-AuthMode.LIMITED. אם התוסף לא מופעל ורק מותקן, onOpen() פועל ב-AuthMode.NONE.

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

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

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
גישה לנתוני משתמשים Locale only לוקאל בלבד לוקאל בלבד כן
גישה למסמך, לטופס, למצגת או לגיליון אלקטרוני לא כן כן – לקריאה בלבד כן
גישה לממשק המשתמש הוספת פריטים לתפריט הוספת פריטים לתפריט לא כן
גישה אל Properties לא כן כן כן
גישה אל Jdbc, ‏ UrlFetch לא לא כן כן
שירותים אחרים Logger
Utilities		 שירותים שלא ניגשים לנתוני משתמשים שירותים שלא ניגשים לנתוני משתמשים כל השירותים

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

כשתוסף מותקן אצל המשתמש הנוכחי או מופעל בקובץ הנוכחי, התוסף נטען במסמך, בטופס, במצגת או בגיליון האלקטרוני כשהקובץ נפתח. התוסף מופיע בתפריט תוספים ומתחיל להאזין לטריגרים הפשוטים onInstall(),‏ onOpen() ו-onEdit(). אם משתמש לוחץ על פריט בתפריט Extensions, הוא פועל.

תוסף העריכה מותקן

כשמתקינים תוסף ל-Editor מהחנות, הפונקציה onInstall() שלו פועלת ב-AuthMode.FULL. במצב ההרשאה הזה, התוסף יכול להריץ תרחיש הגדרה מורכב. מומלץ גם להשתמש ב-onInstall() כדי ליצור פריטים בתפריט, כי המסמך, הטופס, המצגת או הגיליון האלקטרוני כבר פתוחים והפונקציה onOpen() לא הופעלה. בדוגמה הבאה מוסבר איך להפעיל את הפונקציה onOpen() מהפונקציה onInstall():

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

תוסף העריכה נפתח

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

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

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