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

טווחים

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

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

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

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

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

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

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

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

בהמשך מפורטים היקפי הרשאות נפוצים לתוספים ל-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`.

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

אסימוני גישה

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

היקפים אחרים

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

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