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

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

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

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

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

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

הצגת היקפים

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

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

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

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

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

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

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

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

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

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

כשאתם יוצרים תוסף ל-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.