המשתמשים צריכים לתת הרשאה לתוספים ולאפליקציות אחרות שניגשים לנתונים שלהם או פועלים בשמם. כשמשתמש מפעיל תוסף בפעם הראשונה, מוצגת בממשק המשתמש של התוסף בקשה להרשאה כדי להתחיל בתהליך ההרשאה.
בתהליך הזה, הבקשה מציינת למשתמש מה האפליקציה מבקשת הרשאה. לדוגמה, תוסף עשוי לבקש הרשאה לקרוא את הודעות האימייל של המשתמשים או ליצור אירועים ביומן שלו. בפרויקט הסקריפט של התוסף מגדירים את ההרשאות הנפרדות האלה כהיקפים של OAuth.
מצהירים על היקפים במניפסט באמצעות מחרוזות של כתובות URL. בתהליך ההרשאה, Apps Script מציג למשתמש תיאור קריא (לבני אדם). לדוגמה, התוסף של Google Workspace עשוי להשתמש בהיקף 'קריאת ההודעה הנוכחית', שכתוב במניפסט בתור https://www.googleapis.com/auth/gmail.addons.current.message.readonly
. בתהליך ההרשאה, תוסף עם ההיקף הזה מבקש מהמשתמש לאפשר לתוסף לראות את הודעות האימייל שלכם כשהתוסף פועל.
צפייה בהיקפים
כדי לראות את ההיקפים שנדרשים לפרויקט הסקריפט כרגע:
- פותחים את פרויקט הסקריפט.
- בצד ימין, לוחצים על Overview .
- אפשר לראות את ההיקפים בקטע 'היקפי 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 לפני שיהיה אפשר לפרסם אותו. מידע נוסף זמין במדריכים הבאים:
- אימות לקוח OAuth עבור Apps Script
- אפליקציות לא מאומתות
- שאלות נפוצות לגבי אימות OAuth
- שירות Google APIs: המדיניות בנושא נתוני משתמשים
היקפים מוגבלים
היקפים מסוימים מוגבלים וכפופים לכללים נוספים שעוזרים להגן על נתוני המשתמשים. אם אתם מתכוונים לפרסם תוסף של Gmail או עריכה עם היקף מוגבל אחד או יותר, התוסף חייב לעמוד בכל המגבלות שצוינו לפני שאפשר יהיה לפרסם אותו.
חשוב לעיין ברשימה המלאה של ההיקפים המוגבלים לפני שמנסים לפרסם. אם התוסף משתמש באחד מהם, עליכם לעמוד בדרישות הנוספות להיקפי API ספציפיים לפני הפרסום.
היקפי ההרשאות של היומן
בהמשך מפורטים היקפי הרשאות נפוצים לתוספים ל-Google Workspace שמרחיבים את יומן Google.
היקף | |
---|---|
גישה למטא-נתונים של אירוע |
https://www.googleapis.com/auth/calendar.addons.execute
חובה אם התוסף ניגש למטא-נתונים של אירועים ביומן. התוסף יכול לגשת למטא-נתונים של האירוע. |
לקרוא נתוני אירועים שנוצרו על ידי משתמשים |
https://www.googleapis.com/auth/calendar.addons.current.event.read
חובה אם התוסף צריך לקרוא נתוני אירועים שנוצרו על ידי משתמשים.
ההרשאה הזו מאפשרת לתוסף לגשת לנתוני אירועים שנוצרו על ידי משתמשים. הנתונים האלה
זמינים רק אם
שדה המניפסט |
כתיבת נתוני אירועים שנוצרו על ידי משתמשים |
https://www.googleapis.com/auth/calendar.addons.current.event.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 הבסיסי. הרשאת הגישה לקובץ ניתנת על בסיס כל קובץ בנפרד, והיא
מבוטלת כשהמשתמש מבטל את הרשאת האפליקציה. |
היקפי הרשאות של תוספים ל-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
לקרוא את כל המטא-נתונים והתוכן של הודעות האימייל, כולל ההודעה הפתוחה. חובה אם צריך לקרוא מידע על הודעות אחרות, למשל בזמן ביצוע שאילתת חיפוש או קריאת שרשור אימייל שלם. |
אסימוני גישה
כדי להגן על נתוני המשתמשים, היקפי ההרשאות ב-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
חובה אם התוסף ניגש ל-Apps Script Sheets API. הענקת גישה זמנית לתוכן של הגיליון האלקטרוני הפתוח. |
הגישה הנוכחית לקבצים ב-Slides |
https://www.googleapis.com/auth/presentations.currentonly
חובה אם התוסף ניגש ל-API של Slides ב-Apps Script. הענקת גישה זמנית לתוכן של המצגת הפתוחה. |
גישה לכל קובץ |
https://www.googleapis.com/auth/drive.file
חובה כדי שהתוסף יוכל להשתמש ב- |
היקפים אחרים
ייתכן שהתוסף יצטרך היקפים נוספים אם הוא משתמש בשירותים אחרים של Apps Script. ברוב המקרים ניתן לאפשר ל-Apps Script לזהות את ההיקפים האלה ולעדכן את המניפסט באופן אוטומטי. כשעורכים את רשימת ההיקפים של המניפסט, חשוב לא להסיר היקפים אלא אם מחליפים אותם בחלופה מתאימה יותר, כמו היקף מצומצם יותר.
ריכזנו כאן רשימה של היקפי הרשאות בסקריפט של Apps שנעשה בהם שימוש לעיתים קרובות בשילוב עם תוספים ל-Google Workspace:
היקף | |
---|---|
קריאת כתובת האימייל של המשתמש |
https://www.googleapis.com/auth/userinfo.email
מאפשר לפרויקט לקרוא את כתובת האימייל של המשתמש הנוכחי. |
התרת שיחות לשירותים חיצוניים |
https://www.googleapis.com/auth/script.external_request
מאפשר לפרויקט לשלוח בקשות של |
קריאת הלוקאל ואזור הזמן של המשתמש |
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. מידע נוסף זמין במאמר יצירת משאבים של צד שלישי מתפריט ה-@. |