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

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

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