טווחים

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

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

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

הצגת היקפים

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

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

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

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

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

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

אתם יכולים להגדיר באופן מפורש את ההיקפים שפרויקט הסקריפט משתמש בהם על ידי עריכה של קובץ המאניפסט שלו. השדה manifest 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 Developer Tools ל-Visual Studio Code מספק מידע אבחוני לכל היקפי ההרשאות, כולל תיאור היקף ההרשאות ומידע על הרגישות או ההגבלה שלו.

בחירת היקפי הרשאות לתוספים ל-Google Workspace

בקטעים הבאים מפורטים היקפי הרשאות שמשמשים בדרך כלל לתוספים של Google Workspace.

היקפי הרשאות עריכה

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

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

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

Gmail

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

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

חשוב גם להחליף את ההיקף הרחב מאוד 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` ההרשאה מאפשרת גישה לתוכן של ההודעה הפתוחה אחרי אינטראקציה של המשתמש, למשל כשבוחרים פריט בתפריט של תוסף. נדרש טוקן גישה.
קריאת תוכן של שרשור פתוח	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` ההרשאה הזו מעניקה גישה זמנית למטא-נתונים ולתוכן של ההודעה הפתוחה. ההרשאה הזו מעניקה גם גישה לתוכן של הודעות אחרות בשרשור הפתוח. נדרש טוקן גישה.
קריאת תוכן ומטא-נתונים של כל הודעה	`https://www.googleapis.com/auth/gmail.readonly` לקרוא את המטא-נתונים והתוכן של כל אימייל, כולל ההודעה הפתוחה. נדרש אם רוצים לקרוא מידע על הודעות אחרות, למשל כשמבצעים שאילתת חיפוש או קוראים שרשור אימייל שלם. אזהרה: זהו היקף מוגבל רחב מאוד. משתמשים בו רק אם אין ברירה אחרת.

היקפי גישה ביומן Google

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

היקף
גישה למטא-נתונים של אירועים	`https://www.googleapis.com/auth/calendar.addons.execute` נדרשת אם התוסף ניגש למטא נתונים של אירועים ביומן. מאפשרת לתוסף לגשת למטא-נתונים של אירועים.
קריאת נתוני אירועים שנוצרו על ידי משתמשים	`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`.

היקפי גישה ב-Google Chat

כדי לבצע קריאה ל-Chat API, צריך לבצע אימות בתור משתמש ב-Google Chat או בתור אפליקציה ל-Chat. כל סוג של אימות דורש היקפי הרשאות שונים, ולא כל השיטות של Chat API תומכות באימות אפליקציות.

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

בטבלה הבאה מוצגים היקפי ההרשאות ושיטות ה-API הנפוצות ב-Chat, על סמך סוגי האימות הנתמכים:

שיטה	אימות אפליקציה נתמך	היקפי הרשאות נתמכים
אני רוצה לשלוח הודעה		עם אימות משתמשים: `chat.messages.create` `chat.messages` `chat.import` עם אימות אפליקציות: `chat.bot`
איך יוצרים מרחבים		עם אימות משתמשים: `chat.spaces.create` `chat.spaces` `chat.import` עם אימות אפליקציות ואישור אדמין (זמין בגרסת Developer Preview): `chat.app.spaces.create` `chat.app.spaces`
איך יוצרים מרחבים ומוסיפים אליהם משתתפים	—	עם אימות משתמשים: `chat.spaces.create` `chat.spaces`
איך מוסיפים משתמשים למרחבים		עם אימות משתמשים: `chat.memberships` `chat.memberships.app` `chat.import` עם אימות אפליקציות ואישור אדמין (זמין בגרסת Developer Preview): `chat.app.memberships`
רשימת פעילויות או אירועים במרחב ב-Chat	—	באימות משתמשים, צריך להשתמש בהיקף לכל סוג אירוע שכלול בבקשה: לאירועים שקשורים להודעות: `chat.messages` `chat.messages.readonly` לאירועים שקשורים לתגובות באמוג'י: `chat.messages.reactions` `chat.messages.reactions.readonly` `chat.messages` `chat.messages.readonly` לאירועים שקשורים למועדון החברים: `chat.memberships` `chat.memberships.readonly` לאירועים שקשורים למרחב: `chat.spaces` `chat.spaces.readonly`

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

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

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

גישה לכל קובץ

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

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

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

אסימוני גישה

כדי להגן על נתוני המשתמשים, היקפי הגישה של 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();
}

היקפים אחרים של Google Workspace

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

בטבלה הבאה מפורטות רשימת ההיקפים שבהם תוספים ל-Google Workspace משתמשים לעיתים קרובות:

היקף
קריאת כתובת האימייל של המשתמש	`https://www.googleapis.com/auth/userinfo.email` מאפשרת לפרויקט לקרוא את כתובת האימייל של המשתמש הנוכחי.
התרת שיחות לשירותים חיצוניים	`https://www.googleapis.com/auth/script.external_request` מאפשרת לפרויקט לשלוח בקשות `UrlFetch`. הדרישה הזו חלה גם אם הפרויקט משתמש בספרייה OAuth2 for 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. מידע נוסף זמין במאמר יצירת משאבים של צד שלישי באמצעות התפריט @.