היקפים

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

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

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

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

הצגת היקפים

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

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

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

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

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

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

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

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

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

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

התוסף Google Workspace כלים למפתחים ל-Visual Studio Code מספק מידע אבחוני לכל היקפי ההרשאות, כולל תיאור ההיקף והאם הוא רגיש או מוגבל.

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

בקטעים הבאים מפורטים היקפי גישה שמשמשים בדרך כלל לתוספים של Google Workspace.

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

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

היקף
גישה לקובץ Docs הנוכחי https://www.googleapis.com/auth/documents.currentonly

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

חובה אם התוסף משתמש ב טריגרים של פעולת כתיבה. הרשאה שמאפשרת לתוסף ליצור באופן זמני טיוטות חדשות של הודעות ותשובות. פרטים נוספים זמינים במאמר בנושא יצירת טיוטות של הודעות. היקף ההרשאה הזה משמש לעיתים קרובות עם [פעולות כתיבה] (/workspace/add-ons/gmail/extending-compose-ui). נדרש טוקן גישה.

קריאת מטא-נתונים של הודעות פתוחות 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

כדי לבצע קריאה ל-Google 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
עם אימות אפליקציות ואישור אדמין (זמין בתצוגה מקדימה למפתחים):
  • chat.app.spaces.create
  • chat.app.spaces
איך יוצרים מרחבים ומוסיפים אליהם משתתפים — עם אימות משתמשים:
  • chat.spaces.create
  • chat.spaces
איך מוסיפים משתמשים למרחבים עם אימות משתמשים:
  • chat.memberships
  • chat.memberships.app
  • chat.import
באמצעות אימות אפליקציות ואישור אדמין (זמין בתצוגה מקדימה למפתחים):
  • 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. מעניקה גישה לכל קובץ בנפרד לקבצים שנוצרו או נפתחו על ידי האפליקציה באמצעות שירות Drive המתקדם של Apps Script. הפעולה הזו לא מאפשרת לבצע פעולות דומות באמצעות שירות Drive הבסיסי. הרשאת הגישה לקובץ ניתנת לכל קובץ בנפרד, והיא מבוטלת אם המשתמש מבטל את ההרשאה לאפליקציה. כאן אפשר לראות דוגמה לבקשת גישה לקבצים נבחרים.

אסימוני גישה

כדי להגן על נתוני המשתמשים, היקפי הגישה של Gmail שמשמשים בתוספים של Google Workspace מעניקים גישה זמנית לנתוני המשתמשים. כדי להפעיל גישה זמנית, צריך להתקשר אל GmailApp.setCurrentMessageAccessToken באמצעות אסימון גישה מאובייקט של אירוע פעולה.

טוקן הגישה שמאפשר גישה להיקפי Gmail לא זהה לטוקן הגישה שמוחזר על ידי ScriptApp.getOAuthToken. משתמשים בטוקן שמופיע באובייקט של אירוע הפעולה.

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