היקפי הרשאה לתוספים של עורך

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

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

מגדירים היקפי הרשאות במניפסט באמצעות מחרוזות של כתובות URL. במהלך תהליך ההרשאה, Apps Script מציג למשתמש תיאור של היקף ההרשאה שקל להבין. לדוגמה, יכול להיות שהתוסף שלכם משתמש בהיקף ההרשאות 'קריאת המסמך הנוכחי', שמופיע במניפסט כ-https://www.googleapis.com/auth/documents.currentonly. במהלך תהליך ההרשאה, תוסף עם היקף ההרשאה הזה מבקש מהמשתמש לאשר לתוסף את הפעולות הבאות: הצגה וניהול של המסמכים שהותקנה בהם האפליקציה הזאת.

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

צפייה בהיקפים

כדי לראות את ההיקפים שהפרויקט של הסקריפט דורש כרגע:

1. פותחים את פרויקט הסקריפט.
2. בצד ימין, לוחצים על סקירה כללית info_outline.
3. היקפי ההרשאות מופיעים בקטע Project OAuth Scopes (היקפי ההרשאות של OAuth בפרויקט).

אפשר גם לראות את ההיקפים הנוכחיים של פרויקט הסקריפט במניפסט של הפרויקט, בשדה oauthScopes, אבל רק אם הגדרתם את ההיקפים האלה במפורש.

הגדרת היקפים מפורשים

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

לדוגמה, יכול להיות ש-Apps Script ייתן לפרויקט של סקריפט תוסף את ההיקף הרחב מאוד https://mail.google.com כברירת מחדל. כשמשתמש מאשר פרויקט של סקריפט עם ההיקף הזה, הפרויקט מקבל גישה מלאה לחשבון Gmail של המשתמש. בתוספים שפורסמו, חובה להחליף את היקף ההרשאה הזה בסט מוגבל יותר של הרשאות שכולל רק את ההרשאות שהתוסף צריך, ולא יותר.

אתם יכולים להגדיר באופן מפורש את ההיקפים שבהם פרויקט הסקריפט משתמש על ידי עריכה של קובץ המאניפסט שלו. השדה manifest oauthScopes הוא מערך של כל ההיקפים שבהם נעשה שימוש בתוסף. כדי להגדיר את היקפי ההרשאות של הפרויקט:

1. איך רואים את ההיקפים שהתוסף משתמש בהם קובעים אילו שינויים צריך לבצע, למשל להשתמש בהיקף מצומצם יותר.
2. פותחים את קובץ המניפסט של התוסף.
3. מאתרים את השדה ברמה העליונה עם התווית oauthScopes. אם הוא לא מופיע, אפשר להוסיף אותו.

4. השדה oauthScopes מציין מערך של מחרוזות. כדי להגדיר את ההיקפים שבהם הפרויקט משתמש, מחליפים את התוכן של המערך הזה בהיקפים שרוצים שהפרויקט ישתמש בהם. לדוגמה, אם יש לכם תוסף של Editor שמרחיב את Sheets, יכול להיות שיהיה לכם את הקוד הבא:

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/script.container.ui",
        "https://www.googleapis.com/auth/spreadsheets"
      ],
      ...
    }
   

5. שומרים את השינויים בקובץ המניפסט.

אימות OAuth

יכול להיות ששימוש בהיקפי OAuth רגישים מסוימים יחייב אתכם להעביר את התוסף שלכם אימות של לקוח OAuth לפני שתוכלו לפרסם אותו. מידע נוסף זמין במדריכים הבאים:

• אימות לקוח OAuth ב-Apps Script
• אפליקציות לא מאומתות
• שאלות נפוצות לגבי אימות OAuth
• המדיניות של Google בנושא נתוני משתמשים בשירותי API

היקפי הרשאות מוגבלים

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

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

התוסף Google Workspace Developer Tools ל-Visual Studio Code מספק מידע אבחוני לכל היקפי ההרשאות, כולל תיאור היקף ההרשאות והאם הוא רגיש או מוגבל.

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

כשמפתחים תוסף לעורך, היקפי ההרשאות הנדרשים נקבעים על ידי השירות והשיטות של Google Apps Script שבהם נעשה שימוש בקוד התוסף. לדוגמה, יכול להיות שתוסף ל-Google Sheets יזדקק להיקף https://www.googleapis.com/auth/spreadsheets.readonly כדי לקרוא מידע מגיליונות שונים.

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

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

/**
 * @OnlyCurrentDoc
 */

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