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

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

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

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

הערה: ההיקף currentonly זמין רק בשירותי Apps Script. ההגנה הזו לא כוללת את השירותים המתקדמים של Apps Script או קריאות ישירות ל-API של Google Workspace.

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

הצגת היקפים

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

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

היקפים מוגבלים

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

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

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

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

הערה: ההיקף currentonly זמין רק בשירותי Apps Script. ההגנה הזו לא כוללת את השירותים המתקדמים של Apps Script או קריאות ישירות ל-API של Google Workspace.