היקפים

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

במהלך התהליך הזה, ההנחיה אומרת למשתמש מה האפליקציה רוצה לעשות. לדוגמה, תוסף עשוי לבקש הרשאה לקרוא הודעת אימייל של משתמש או ליצור אירועים ביומן שלו. פרויקט הסקריפט של התוסף מגדיר את ההרשאות האישיות האלה כהיקפי הרשאות ל-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 Developer Tools ל-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 ואם התוסף ניגש ל-Docs,‏ Sheets,‏ Slides או ל-Drive API. הענקת גישה לקבצים שנוצרו או נפתחו על ידי האפליקציה באמצעות שירות 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 או בתור אפליקציית Google 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. מידע נוסף זמין במאמר בנושא יצירת משאבים של צד שלישי מהתפריט @.