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

טווחים

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

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

מגדירים היקפי הרשאות במניפסט באמצעות מחרוזות של כתובות URL. במהלך תהליך ההרשאה, Apps Script מציג למשתמש תיאור של היקף ההרשאה שקל להבין. לדוגמה, תוסף ל-Google Workspace עשוי להשתמש בהיקף ההרשאות Read current message (קריאת ההודעה הנוכחית), שמופיע בקובץ המניפסט כ-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. ההרשאה מאפשרת גישה לקבצים שנוצרו או נפתחו על ידי האפליקציה, באמצעות שירות Advanced 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.

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

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