היקפי הרשאות

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

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

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

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

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

מחליפים את התוכן של המערך oauthScopes בהיקפי ההרשאות שרוצים שהפרויקט ישתמש בהם. לדוגמה:

      {
        ...
        "oauthScopes": [
          "https://www.googleapis.com/auth/spreadsheets.readonly",
          "https://www.googleapis.com/auth/userinfo.email"
        ],
       ...
      }

למעלה, לוחצים על שמירה .

טיפול בהרשאות OAuth מפורטות

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

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

בקטעים הבאים מוסבר איך לטפל בהרשאות OAuth גרנולריות.

דרישת הרשאה אוטומטית להיקפי הרשאות נדרשים

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

השיטות הבאות מהמחלקה ScriptApp מאמתות הרשאות ומציגות את בקשת ההרשאה:

‫requireScopes(authMode, oAuthScopes): משתמשים בשיטה הזו לתהליכים שמסתמכים על היקפי הרשאות ספציפיים.
‫requireAllScopes(authMode): משתמשים בשיטה הזו אם תהליך ההפעלה מסתמך על כל ההיקפים של הפרויקט.

דוגמה

בדוגמה הבאה אפשר לראות איך מפעילים את requireScopes() ואת requireAllScopes(). הסקריפט משתמש בהיקפי הרשאות ל-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 לבקשת הרשאות חסרות, משתמשים בשיטות ממחלקת AuthorizationInfo.

דוגמה

בדוגמה הבאה אפשר לראות איך משתמשים ב-getAuthorizationInfo() כדי לדלג על תכונות שבהן המשתמשים לא העניקו את היקפי ההרשאות הנדרשים. כך אפשר להמשיך את שאר התהליך בלי לבקש הרשאה להיקפי ההרשאות החסרים.

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

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

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

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

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

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

הצגת היקפים

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

טיפול בהרשאות OAuth מפורטות

דרישת הרשאה אוטומטית להיקפי הרשאות נדרשים

דוגמה

יצירת חוויה מותאמת אישית למקרים שבהם חסרים היקפי הרשאות

דוגמה

מוודאים שלטריגרים יש הרשאות להפעלה

דוגמה

אימות OAuth

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

היקפי הרשאות