טווחים

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

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

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

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

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

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

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

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

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

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

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

גישה לקובץ https://www.googleapis.com/auth/drive.file

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

לצפייה בקשת גישה לקבצים מסוימים לדוגמה.

היקפי הרשאות של תוספים ל-Gmail

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

בהמשך מפורטים היקפי הרשאות שנמצאים בשימוש נפוץ לתוספים של Google Workspace שמרחיבים את Gmail: חובה להוסיף את המילים חובה אל מניפסט של תוסף ל-Google Workspace, אם התוסף מורחב Gmail.

חשוב גם להחליף את ההיקף הרחב מאוד של 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();
}

היקפי ההרשאות של Editor

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

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