דף זה תורגם על ידי Cloud Translation API.

טווחים

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

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

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

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

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

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

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

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

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

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

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

הצגת היקפי ההרשאות שהתוסף משתמש בהם כרגע מחליטים מה צריכים לעשות שינויים, למשל להשתמש בהיקף מצומצם יותר.
פותחים את קובץ המניפסט של התוסף.
מאתרים את השדה ברמה העליונה בשם oauthScopes. אם הוא לא נמצא, אפשר להוסיף אותו.
oauthScopes מציין מערך של מחרוזות. כדי להגדיר את היקפי ההרשאות בפרויקט שלכם, מחליפים את התוכן של המערך בהיקפים שצריך להשתמש בו. לדוגמה, אם מדובר בתוסף של Google Workspace שמרחיב את Gmail, יכול להיות שיש לכם:
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
שומרים את השינויים בקובץ המניפסט.

אימות OAuth

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

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

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

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

היקפי ההרשאות של היומן

בהמשך מפורטים היקפי ההרשאות שנמצאים בשימוש נפוץ לתוספים ל-Google Workspace שמרחיבים את יומן Google.

היקף
גישה למטא-נתונים של אירועים	`https://www.googleapis.com/auth/calendar.addons.execute` חובה אם התוסף ניגש למטא-נתונים של אירועים ביומן Google אישור התוסף כדי לגשת למטא-נתונים של אירועים.
קריאה של נתוני אירועים שנוצרו על ידי משתמשים	`https://www.googleapis.com/auth/calendar.addons.current.event.read` חובה אם התוסף צריך לקרוא נתוני אירועים שנוצרו על ידי משתמשים. מאפשרת לתוסף לגשת לנתוני אירועים שנוצרו על ידי משתמשים. הנתונים האלה זמינה רק אם שדה מניפסט אחד (`addOns.calendar.eventAccess`) מוגדר ל-`READ` או `READ_WRITE`.
כתיבת נתוני אירועים שנוצרו על ידי משתמשים	`https://www.googleapis.com/auth/calendar.addons.current.event.write` חובה אם התוסף צריך לכתוב נתוני אירועים שנוצרו על ידי משתמשים. מאפשרת לתוסף לערוך נתוני אירועים שנוצרו על ידי משתמשים. הנתונים האלה זמינה רק אם שדה מניפסט אחד (`addOns.calendar.eventAccess`) מוגדר ל-`WRITE` או `READ_WRITE`.

היקפי הרשאות ב-Drive

בהמשך מפורטים היקפי ההרשאות שנמצאים בשימוש נפוץ לתוספים של Google Workspace שמרחיבים את Google Drive.

היקף

קריאת המטא-נתונים של הפריט שנבחר

היקף
קריאת המטא-נתונים של הפריט שנבחר	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` חובה אם התוסף מיישם ממשק לפי הקשר שמופעל כשהמשתמש בוחר פריטים ב-Drive. לתוסף תהיה הרשאה לקרוא מטא-נתונים מוגבלים לגבי פריטים שיש למשתמש שנבחרו ב-Google Drive. המטא-נתונים מוגבלים למזהה הפריט. שם, סוג MIME, כתובת URL של הסמל ואם לתוסף יש הרשאה ניגשים לפריט.
גישה לקובץ	`https://www.googleapis.com/auth/drive.file` מומלץ אם לתוסף צריך גישה ל-Drive ספציפי . מעניק גישה לכל קובץ לקבצים שנוצרו או נפתחו על ידי האפליקציה, באמצעות Apps Script Drive – Advanced Drive שירות. היא לא מאפשרת להשתמש בפעולות דומות באמצעות שירות בסיסי של Drive, עם זאת. הרשאת הגישה לקובץ מוענקת לכל קובץ בנפרד, תבוטל כשהמשתמש מבטל את ההרשאה של האפליקציה. לצפייה בקשת גישה לקבצים מסוימים לדוגמה.

https://www.googleapis.com/auth/drive.addons.metadata.readonly

חובה אם התוסף מיישם ממשק לפי הקשר שמופעל כשהמשתמש בוחר פריטים ב-Drive. לתוסף תהיה הרשאה לקרוא מטא-נתונים מוגבלים לגבי פריטים שיש למשתמש שנבחרו ב-Google Drive. המטא-נתונים מוגבלים למזהה הפריט. שם, סוג MIME, כתובת URL של הסמל ואם לתוסף יש הרשאה ניגשים לפריט.

גישה לקובץ

https://www.googleapis.com/auth/drive.file

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

לצפייה בקשת גישה לקבצים מסוימים לדוגמה.

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

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

בהמשך מפורטים היקפי הרשאות שנמצאים בשימוש נפוץ לתוספים של Google Workspace שמרחיבים את Gmail: חובה להוסיף את המילים חובה אל מניפסט של תוסף Google Workspace, אם התוסף ארוך Gmail.

חשוב גם להחליף את ההיקף הרחב מאוד של https://mail.google.com ב- תוסף עם קבוצה מצומצמת יותר של היקפים שמאפשרים את האינטראקציות ולא יותר.

היקף
ליצור טיוטות חדשות	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` חובה אם התוסף משתמש טריגרים של פעולות כתיבה. מאפשרת לתוסף ליצור טיוטות חדשות של הודעות באופן זמני תשובות. ראו כתיבת טיוטות של הודעות לקבלת פרטים. משתמשים בהיקף הזה גם פעולות כתיבה. נדרש אסימון גישה.
קריאת המטא-נתונים של ההודעה הפתוחה	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` התפקיד הזה מעניק גישה זמנית למטא-נתונים של ההודעה הפתוחה (למשל נושא או נמענים). אי אפשר לקרוא את תוכן ההודעות והוא מחייב אסימון גישה. חובה אם התוסף משתמש במטא-נתונים בפעולת הכתיבה טריגרים. עבור פעולות כתיבה, ההיקף הזה נדרש אם טריגר לכתיבה צריכה גישה למטא-נתונים. בפועל, ההיקף הזה מאפשר הפעלת רשימות של נמענים (אל:, :עותק ועותק מוסתר) של תשובה טיוטת אימייל.
קריאת התוכן של ההודעות הפתוחות	`https://www.googleapis.com/auth/gmail.addons.current.message.action` התפקיד הזה מעניק גישה לתוכן של ההודעה הפתוחה בעקבות אינטראקציה של המשתמש, למשל, כשבוחרים אפשרות בתפריט של תוסף. נדרשת גישה ב-Assistant.
קריאת התוכן של השרשור הפתוח	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` התפקיד הזה מעניק גישה זמנית למטא-נתונים ולתוכן של ההודעה הפתוחה. מעניק גם גישה לתוכן של הודעות אחרות בחלון הפתוח של שרשור. נדרש אסימון גישה.
קריאת התוכן והמטא-נתונים של ההודעות	`https://www.googleapis.com/auth/gmail.readonly` לקרוא את כל התוכן והמטא-נתונים של האימייל, כולל ההודעה הפתוחה. נדרש אם צריך לקרוא מידע על הודעות אחרות, כמו כשמבצעים שאילתת חיפוש או קוראים שרשור אימייל שלם. אזהרה: זו אזהרה רחבה מאוד, היקף מוגבל. יש להשתמש באפשרות הזו רק אם בהחלט הכרחי.

אסימוני גישה

כדי להגן על נתוני המשתמשים, ההיקפים של Gmail שבהם נעשה שימוש הענקת גישה לתוספים ל-Google Workspace בלבד גישה זמנית לנתוני משתמשים. כדי להפעיל גישה זמנית, צריך לקרוא ל פונקציה GmailApp.setCurrentMessageAccessToken(accessToken) באמצעות אסימון גישה כארגומנט. עליך לקבל אסימון גישה אובייקט אירוע פעולה.

בדוגמה הבאה מוצגת דוגמה להגדרה של אסימון גישה כדי לאפשר גישה אל המטא-נתונים של הודעה. ההיקף היחיד הדרוש לדוגמה הזו הוא https://www.googleapis.com/auth/gmail.addons.current.message.metadata

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

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

בהמשך מפורטים היקפי הרשאות שנמצאים בשימוש נפוץ לתוספים של Google Workspace שמרחיבים את Docs, Sheets, ו-Slides.

היקף
הגישה הנוכחית לקובצי Docs	`https://www.googleapis.com/auth/documents.currentonly` חובה אם התוסף ניגש ל-Apps Script Docs API. התפקיד הזה מעניק גישה זמנית לתוכן של המסמך הפתוח.
הגישה הנוכחית לקובץ ב-Sheets	`https://www.googleapis.com/auth/spreadsheets.currentonly` חובה אם התוסף ניגש ל-Apps Script Sheets API. התפקיד הזה מאפשר גישה זמנית לתוכן של הגיליון האלקטרוני הפתוח.
הגישה הנוכחית לקבצים ב-Slides	`https://www.googleapis.com/auth/presentations.currentonly` חובה אם התוסף ניגש ל-Apps Script Slides API. התפקיד הזה מעניק גישה זמנית לתוכן של המצגת הפתוחה.
גישה לקובץ	`https://www.googleapis.com/auth/drive.file` חובה שהתוסף יוכל להשתמש ב-`onFileScopeGrantedTrigger` ואם התוסף ניגש ל-API של Docs, Sheets, Slides או Drive. מעניק גישה לכל קובץ לקבצים שנוצרו או נפתחו על ידי האפליקציה, באמצעות Apps Script Drive – Advanced Drive שירות. היא לא מאפשרת להשתמש בפעולות דומות באמצעות שירות בסיסי של Drive, עם זאת. הרשאת הגישה לקובץ מוענקת לכל קובץ בנפרד, מבוטלת כשהמשתמש מבטל את הרשאת האפליקציה.

היקפים אחרים

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

לידיעתך, הנה רשימה של היקפים ב-Apps Script שנמצאים בשימוש לעיתים קרובות ב בשילוב עם התוספים של Google Workspace:

היקף
קריאת כתובת האימייל של המשתמש	`https://www.googleapis.com/auth/userinfo.email` מאפשר לפרויקט לקרוא את כתובת האימייל של המשתמש הנוכחי.
אישור שיחות לשירותים חיצוניים	`https://www.googleapis.com/auth/script.external_request` מאפשר לפרויקט `UrlFetch` בקשות. הדבר נדרש גם אם הפרויקט משתמש ב- ספריית OAuth2 ל-Apps Script.
קריאת האזור ואזור הזמן של המשתמש	`https://www.googleapis.com/auth/script.locale` מאפשר לפרויקט ללמוד את הלוקאל ואזור הזמן של המשתמש הנוכחי. ראו גישה ללוקאל ולאזור הזמן של המשתמש לקבלת פרטים.
יצירת טריגרים	`https://www.googleapis.com/auth/script.scriptapp` מאפשר לפרויקט ליצור טריגרים.
תצוגה מקדימה של קישורים של צד שלישי	`https://www.googleapis.com/auth/workspace.linkpreview` חובה אם התוסף מציג תצוגה מקדימה של קישורים משירות צד שלישי. מאפשרת לפרויקט לראות קישור באפליקציה של Google Workspace בזמן שהמשתמש יוצר איתה אינטראקציה. מידע נוסף זמין במאמר תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים
יצירת משאבים של צד שלישי	`https://www.googleapis.com/auth/workspace.linkcreate` חובה אם התוסף יוצר משאבים בשירות של צד שלישי. מאפשר לפרויקט לקרוא את המידע שהמשתמשים שולחים אליו את הטופס ליצירת המשאב להוסיף קישור למשאב באפליקציה של Google Workspace. מידע נוסף זמין במאמר יצירת משאבים של צד שלישי מתפריט ה-@.