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

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

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

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

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

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

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

מודל ההרשאות

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

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

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

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

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

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

מצבי הרשאה

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

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

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

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

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

    כשיוצרים פריסת בדיקה, צריך לוודא שהשדה Config (הגדרה) היא מותקן למשתמש הנוכחי, ושהטקסט שמתחת לתיבת ההגדרה מציין בדיקה בAuthMode.None

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

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