טווחים

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

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

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

הצגת היקפים

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

1. פותחים את פרויקט הסקריפט.
2. בצד ימין, לוחצים על סקירה כללית info_outline.
3. אפשר לראות את ההיקפים בקטע 'היקפי OAuth בפרויקט'.

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

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

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

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

אתם יכולים להגדיר באופן מפורש את ההיקפים שבהם פרויקט הסקריפט משתמש על ידי עריכת קובץ manifest שלו. השדה manifest‏ oauthScopes הוא מערך של כל ההיקפים שבהם נעשה שימוש בתוסף. כדי להגדיר את ההיקפים של הפרויקט:

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

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

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

5. שומרים את השינויים בקובץ המניפסט.

אימות OAuth

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

• אימות לקוחות OAuth ב-Apps Script
• אפליקציות שלא אומתו
• שאלות נפוצות בנושא אימות OAuth
• שירות Google APIs: המדיניות בנושא נתוני משתמשים

היקפי גישה מוגבלים

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

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

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

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

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

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

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

אסימוני גישה

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