דף זה תורגם על ידי 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 של המשתמש. ב-Add-ons שפורסמו, חובה להחליף את ההיקף הזה בקבוצה מוגבלת יותר שמתאימה לצרכים של ה-Add-on ולא יותר.

אתם יכולים להגדיר באופן מפורש את ההיקפים שבהם פרויקט הסקריפט משתמש על ידי עריכת קובץ המניפסט שלו. שדה המניפסט 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 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. הענקת גישה זמנית לתוכן של המסמך הפתוח.
הגישה הנוכחית שלכם לקבצים ב-Sheets	`https://www.googleapis.com/auth/spreadsheets.currentonly` חובה אם התוסף ניגש ל-Sheets API של Apps Script. הענקת גישה זמנית לתוכן של הגיליון האלקטרוני הפתוח.
גישה לקבצים של השקפים הנוכחיים	`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.

חשוב גם להחליף את ההיקף 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` נדרשת אם התוסף ניגש למטא-נתונים של אירועים ביומן 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`.

היקפי הרשאה ב-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. למידע נוסף, ראו יצירת משאבים של צד שלישי מהתפריט '@'.