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

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

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

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

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

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

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

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

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

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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

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