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

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

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

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

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

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

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

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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

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