דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

במהלך תהליך ההרשאה, מערכת Apps Script מציגה למשתמש תיאורים של היקפי ההרשאות הנדרשים שניתנים לקריאה על ידי בני אדם. לדוגמה, אם ל-script צריכה להיות גישה לקריאה בלבד לגיליונות האלקטרוניים, יכול להיות שההיקף של המניפסט יהיה https://www.googleapis.com/auth/spreadsheets.readonly. במהלך תהליך ההרשאה, סקריפט עם ההיקף הזה יבקש מהמשתמש לאפשר לאפליקציה "להציג את הגיליונות האלקטרוניים שלך ב-Google Sheets".

חלק מההיקפים כוללים היקפים אחרים. לדוגמה, כשנותנים הרשאה להיקף https://www.googleapis.com/auth/spreadsheets, הוא מאפשר גישה לקריאה ולכתיבה לגיליונות אלקטרוניים.

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

הצגת ההיקפים

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

פותחים את פרויקט הסקריפט.
בצד ימין, לוחצים על סקירה כללית .
אפשר לראות את ההיקפים בקטע Project OAuth Scopes.

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

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

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

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

פותחים את פרויקט הסקריפט.
בצד ימין, לוחצים על הגדרות הפרויקט .
מסמנים את התיבה הצגת קובץ המניפסט 'Appscript.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 ויומן Google. בפונקציה 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(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...
}

אימות OAuth

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

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

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

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