משתמשים צריכים לאשר פרויקטים של סקריפטים שגולשים לנתונים שלהם או פועלים בשמם. כשמשתמש מריץ סקריפט שמחייב הרשאה בפעם הראשונה, מוצגת לו בקשה בממשק המשתמש להתחיל את תהליך ההרשאה.
במהלך התהליך הזה, ממשק המשתמש מציג למשתמש את הפעולות שהסקריפט רוצה לבצע. לדוגמה, סקריפט עשוי לבקש הרשאה לקרוא את הודעות האימייל של המשתמש או ליצור אירועים ביומן שלו. בפרויקט הסקריפט מוגדרות ההרשאות האלה כהיקפי הרשאות ל-OAuth.
ברוב הסקריפטים, Apps Script מזהה באופן אוטומטי את ההיקפים שאתם צריכים. אתם יכולים לראות את ההיקפים שבהם סקריפט משתמש בכל שלב. אפשר גם להגדיר היקפים באופן מפורש במניפסט באמצעות מחרוזות של כתובות URL. לפעמים צריך להגדיר את ההיקפים באופן מפורש באפליקציות מסוימות, כמו תוספים, כי אפליקציות שפורסמו צריכות תמיד להשתמש בהיקפים הכי מצומצמים שאפשר.
במהלך תהליך ההרשאה, Apps Script מציג למשתמש תיאורים של היקפי ההרשאות הנדרשים, בשפה פשוטה. לדוגמה, אם הסקריפט צריך גישת קריאה בלבד לגיליונות האלקטרוניים, יכול להיות שבקובץ המניפסט תהיה ההרשאה https://www.googleapis.com/auth/spreadsheets.readonly
. במהלך תהליך ההרשאה, סקריפט עם היקף ההרשאות הזה מבקש מהמשתמש לאפשר לאפליקציה 'לצפות בגיליונות האלקטרוניים שלך ב-Google'.
חלק מההיקפים כוללים היקפים אחרים. לדוגמה, כשמאשרים את היקף ההרשאות https://www.googleapis.com/auth/spreadsheets
, מקבלים גישת קריאה וכתיבה לגיליונות אלקטרוניים.
במקומות מסוימים שבהם מופעלים סקריפטים, כמו הפעלת סקריפט ישירות מ-IDE של Apps Script, מוצג למשתמשים מסך הסכמה מפורט ל-OAuth. כך המשתמשים יכולים לבחור הרשאות ספציפיות שהם רוצים להעניק, במקום להעניק את כל ההרשאות בבת אחת. חשוב לתכנן את הסקריפט כך שיטפל בהרשאות מפורטות של OAuth.
הצגת היקפים
כדי לראות את ההיקפים שפרויקט הסקריפט דורש כרגע:
- פותחים את פרויקט הסקריפט.
- בצד ימין, לוחצים על סקירה כללית .
- היקפי ההרשאות מופיעים בקטע Project OAuth Scopes (היקפי הרשאות OAuth של הפרויקט).
הגדרת היקפי הרשאות מפורשים
Apps Script קובע באופן אוטומטי אילו היקפי הרשאות נדרשים לסקריפט על ידי סריקת הקוד שלו כדי למצוא קריאות לפונקציות שדורשות אותם. ברוב הסקריפטים, זה מספיק וחוסך לכם זמן, אבל בתוספים שפורסמו, באפליקציות אינטרנט, באפליקציות ל-Google Chat ובקריאות ל-Google Chat API, אתם צריכים להפעיל שליטה ישירה יותר בהיקפי ההרשאות.
לפעמים, מערכת Apps Script מקצה אוטומטית לפרויקטים היקפי הרשאות מאוד מתירניים. יכול להיות שהסקריפט יבקש מהמשתמש יותר ממה שהוא צריך, וזו שיטה לא מומלצת. בסקריפטים שפורסמו, צריך להחליף את ההיקפים הרחבים בסט מוגבל יותר שמכסה את הצרכים של הסקריפט ולא יותר.
אתם יכולים להגדיר במפורש את ההיקפים שפרויקט הסקריפט משתמש בהם על ידי עריכה של קובץ המאניפסט שלו. השדה manifest
oauthScopes
הוא מערך של כל ההיקפים שבהם נעשה שימוש בפרויקט. כדי להגדיר את ההיקפים של הפרויקט:
- פותחים את פרויקט הסקריפט.
- בצד ימין, לוחצים על הגדרות הפרויקט .
- מסמנים את התיבה הצגת קובץ המניפסט 'appsscript.json' בעורך.
- בצד ימין, לוחצים על עורך .
- בצד ימין, לוחצים על הקובץ
appsscript.json
. - מאתרים את השדה ברמה העליונה עם התווית
oauthScopes
. אם הוא לא מופיע, אפשר להוסיף אותו. - בשדה
oauthScopes
מצוין מערך של מחרוזות. כדי להגדיר את ההיקפים שבהם הפרויקט משתמש, מחליפים את התוכן של המערך הזה בהיקפים שרוצים שהפרויקט ישתמש בהם. לדוגמה:{ ... "oauthScopes": [ "https://www.googleapis.com/auth/spreadsheets.readonly", "https://www.googleapis.com/auth/userinfo.email" ], ... }
- למעלה, לוחצים על סמל השמירה .
טיפול בהרשאות OAuth מפורטות
מסך ההסכמה המפורט של OAuth מאפשר למשתמשים לציין אילו היקפי OAuth הם רוצים לאשר. הרשאות OAuth מפורטות מאפשרות למשתמשים שליטה מדויקת יותר בנתוני החשבון שהם בוחרים לשתף עם כל סקריפט. לדוגמה, נניח שפיתחתם סקריפט שמבקש הרשאה להיקפי גישה של אימייל ויומן. יכול להיות שהמשתמשים שלכם ירצו להשתמש בסקריפט רק כדי להשתמש ביכולות שלו עם יומן Google, אבל לא עם Gmail. עם הרשאות OAuth מפורטות, המשתמשים יכולים לבחור להעניק הרשאה ליומן בלבד, ולא ל-Gmail.
בקטעים הבאים מתוארות הדרכים העיקריות לניהול הרשאות OAuth ברמת גרנולריות גבוהה.
דרישה אוטומטית להרשאה להיקפי הרשאות נדרשים
אם תהליך ההפעלה צריך הרשאה להיקפים כדי לפעול, אתם יכולים לדרוש מהמשתמשים להעניק את ההרשאות האלה לפני שהם יוכלו להשתמש בו. הסקריפט יכול לבדוק אם המשתמש כבר נתן הרשאה, ואם לא, לבקש ממנו אותה באופן אוטומטי.
השיטות הבאות מהמחלקה ScriptApp
מאפשרות לאמת את ההרשאה להיקפי ההרשאות הנדרשים, ולהציג באופן אוטומטי את בקשת ההרשאה כדי לבקש הרשאות חסרות:
-
requireScopes(authMode, oAuthScopes)
: משתמשים בשיטה הזו לזרימות ביצוע שמסתמכות על היקף אחד או יותר, אבל לא על כל ההיקפים שמשמשים את הסקריפט. -
requireAllScopes(authMode)
: משתמשים בשיטה הזו אם תהליך ההפעלה מסתמך על כל ההיקפים שבהם נעשה שימוש בסקריפט.
דוגמה
בדוגמה הבאה אפשר לראות איך מפעילים את השיטות requireScopes(authMode, oAuthScopes)
ו-requireAllScopes(authMode)
.
הסקריפט משתמש בהיקפים עבור Gmail, Sheets ויומן.
הפונקציה sendEmail()
דורשת רק את היקפי ההרשאות של Gmail ו-Sheets, ואילו הפונקציה createEventSendEmail()
דורשת את כל היקפי ההרשאות שבהם נעשה שימוש בסקריפט.
// This function requires the Gmail and Sheets scopes.
function sendEmail() {
// Validates that the user has granted permission for the Gmail and Sheets scopes.
// If not, the execution ends and prompts the user for authorization.
ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
'https://mail.google.com/',
'https://www.googleapis.com/auth/spreadsheets'
]);
// Sends an email.
GmailApp.sendEmail("dana@example.com", "Subject", "Body");
Logger.log("Email sent successfully!");
// Opens a spreadsheet and sheet to track the sent email.
const ss = SpreadsheetApp.openById("abc1234567");
const sheet = ss.getSheetByName("Email Tracker")
// Gets the last row of the sheet.
const lastRow = sheet.getLastRow();
// Adds "Sent" to column E of the last row of the spreadsheet.
sheet.getRange(lastRow, 5).setValue("Sent");
Logger.log("Sheet updated successfully!");
}
// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
// Validates that the user has granted permission for all scopes used by the
// script. If not, the execution ends and prompts the user for authorization.
ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);
// Creates an event.
CalendarApp.getDefaultCalendar().createEvent(
"Meeting",
new Date("November 28, 2024 10:00:00"),
new Date("November 28, 2024 11:00:00")
);
Logger.log("Calendar event created successfully!");
// Sends an email.
GmailApp.sendEmail("dana@example.com", "Subject 2", "Body 2");
Logger.log("Email sent successfully!");
// Opens a spreadsheet and sheet to track the created meeting and sent email.
const ss = SpreadsheetApp.openById("abc1234567");
const sheet = ss.getSheetByName("Email and Meeting Tracker")
// Gets the last row
const lastRow = sheet.getLastRow();
// Adds "Sent" to column E of the last row
sheet.getRange(lastRow, 5).setValue("Sent");
// Adds "Meeting created" to column F of the last row
sheet.getRange(lastRow, 6).setValue("Meeting created");
Logger.log("Sheet updated successfully!");
}
יצירת חוויה מותאמת אישית להיקפים חסרים
אתם יכולים לקבל את פרטי ההרשאות של המשתמש שמריץ את הסקריפט ולעצב חוויה מותאמת אישית על סמך סטטוס ההרשאות שלו. לדוגמה, אפשר להשבית תכונות ספציפיות בסקריפט שדורשות הרשאות שהמשתמש לא העניק, או להציג תיבת דו-שיח מותאמת אישית עם הסבר על ההרשאות החסרות. השיטות הבאות מקבלות אובייקט עם פרטי ההרשאה של המשתמש, כולל ההיקפים שהמשתמש אישר וכתובת URL שמאפשרת לבקש היקפים חסרים:
-
getAuthorizationInfo(authMode, oAuthScopes)
: אפשר להשתמש בשיטה הזו כדי לבדוק את סטטוס ההרשאות להיקפים ספציפיים. -
getAuthorizationInfo(authMode)
: אפשר להשתמש בשיטה הזו כדי לבדוק את סטטוס ההרשאות של כל ההיקפים שבהם נעשה שימוש בסקריפט.
כדי לקבל את פרטי ההרשאה מאובייקט פרטי ההרשאה, כמו רשימה של ההיקפים שאושרו וכתובת URL לבקשת הרשאות חסרות, משתמשים בשיטות מה-class AuthorizationInfo
.
דוגמה
הדוגמה הבאה מראה איך להפעיל את השיטה getAuthorizationInfo(authMode, oAuthScopes)
כדי לדלג על תכונות ספציפיות בתהליך ההפעלה, במקרים שבהם ההיקפים הנדרשים לא הוענקו. כך ששאר זרימת ההרצה יכולה להימשך בלי שצריך לבקש הרשאה להיקפים החסרים.
// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
GmailApp.sendEmail("dana@example.com", "Subject", "Body");
Logger.log("Email sent successfully!");
} else {
const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
}
// Continue the rest of the execution flow...
}
מוודאים שלטריגרים יש הרשאות להפעלה
פונקציות שמשויכות לטריגרים יכולות לפעול באופן אוטומטי באירועים מסוימים, והמשתמש לא יכול להיות נוכח כדי לספק הרשאות נוספות. מומלץ להשתמש ב-requireScopes(authMode, oAuthScopes)
לפני שמתקינים טריגר. הפעולה הזו תציג למשתמש בקשה להרשאות חסרות, ולא תאפשר את ההתקנה של הטריגר בלעדיהן.
דוגמה
// This function requires scope Sheets.
function trackFormSubmissions(e){
// Opens a spreadsheet to track the sent email.
const ss = SpreadsheetApp.openById("abc1234567");
const sheet = ss.getSheetByName("Submission Tracker")
// Gets the last row of the sheet.
const lastRow = sheet.getLastRow();
// Adds email address of user that submitted the form
// to column E of the last row of the spreadsheet.
sheet.getRange(lastRow, 5).setValue(e.name);
Logger.log("Sheet updated successfully!");
}
function installTrigger(){
// Validates that the user has granted permissions for trigger
// installation and execution. If not, trigger doesn't get
// installed and prompts the user for authorization.
ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
'https://www.googleapis.com/auth/script.scriptapp',
'https://www.googleapis.com/auth/spreadsheets',
'https://www.googleapis.com/auth/forms.currentonly'
]);
ScriptApp.newTrigger('trackFormSubmission')
.forForm(FormApp.getActiveForm())
.onFormSubmit()
.create();
}
אימות OAuth
היקפים מסוימים של OAuth הם רגישים כי הם מאפשרים גישה לנתוני משתמשים ב-Google. אם פרויקט הסקריפט שלכם משתמש בהיקפים שמאפשרים גישה לנתוני משתמשים, הפרויקט צריך לעבור אימות של לקוח OAuth לפני שתוכלו לפרסם אותו באופן ציבורי כאפליקציית אינטרנט או כתוסף. מידע נוסף זמין במדריכים הבאים:
- אימות לקוח OAuth ב-Apps Script
- אפליקציות שלא אומתו
- שאלות נפוצות לגבי אימות OAuth
- המדיניות של Google בנושא נתוני משתמשים בשירותי API
היקפים מוגבלים
בנוסף להיקפי הרשאות רגישים, יש היקפי הרשאות שמסווגים כמוגבלים וכפופים לכללים נוספים שעוזרים להגן על נתוני המשתמשים. אם אתם מתכוונים לפרסם אפליקציית אינטרנט או תוסף שמשתמשים בהיקפי גישה מוגבלים, האפליקציה צריכה לעמוד בכל ההגבלות שצוינו לפני שתוכלו לפרסם אותה.
לפני שמנסים לפרסם, כדאי לעיין ברשימה המלאה של היקפי הרשאות מוגבלים. אם האפליקציה שלכם משתמשת באחת מהן, אתם צריכים לעמוד בדרישות של הדרישות הנוספות להיקפי API ספציפיים לפני הפרסום.