محدوده مجوز

کاربران باید پروژه‌های اسکریپتی را که به داده‌های آنها دسترسی دارند یا از طرف آنها عمل می‌کنند، تأیید کنند. برای یک مرور کلی سطح بالا از این فرآیند، به بخش «مجوزدهی برای سرویس‌های گوگل» مراجعه کنید. وقتی کاربری برای اولین بار اسکریپتی را اجرا می‌کند که نیاز به تأیید دارد، رابط کاربری اعلانی برای شروع جریان تأیید ارائه می‌دهد.

در طول این جریان، رابط کاربری به کاربران می‌گوید که اسکریپت چه مجوزهایی را درخواست می‌کند. برای مثال، یک اسکریپت ممکن است مجوز خواندن پیام‌های ایمیل یا ایجاد رویدادهای تقویم را درخواست کند. پروژه اسکریپت این مجوزهای فردی را به عنوان دامنه‌های OAuth تعریف می‌کند.

برای اکثر اسکریپت‌ها، Apps Script به طور خودکار محدوده‌های مورد نیاز را تشخیص می‌دهد. شما می‌توانید محدوده‌هایی را که یک اسکریپت در هر زمانی استفاده می‌کند، مشاهده کنید . همچنین می‌توانید محدوده‌ها را به طور صریح در مانیفست خود با استفاده از رشته‌های URL تنظیم کنید . برنامه‌های منتشر شده، مانند افزونه‌ها ، باید از محدودترین محدوده‌های ممکن استفاده کنند.

در طول جریان مجوزدهی، Apps Script توضیحات قابل خواندن توسط انسان از محدوده‌های مورد نیاز را ارائه می‌دهد. برای مثال، اگر اسکریپت شما نیاز به دسترسی فقط خواندنی به صفحات گسترده دارد، مانیفست ممکن است شامل محدوده https://www.googleapis.com/auth/spreadsheets.readonly باشد. اعلان مجوز از کاربر می‌خواهد که "صفحه‌های گسترده گوگل خود را مشاهده کند".

برخی از حوزه‌ها شامل موارد دیگری نیز می‌شوند. برای مثال، دسترسی مجاز به https://www.googleapis.com/auth/spreadsheets امکان خواندن و نوشتن در صفحات گسترده را فراهم می‌کند.

برای برخی سطوح، مانند IDE اسکریپت برنامه‌ها، کاربران صفحه رضایت OAuth جزئی را مشاهده می‌کنند. این صفحه به کاربران اجازه می‌دهد مجوزهای خاصی را برای اعطای انتخاب کنند، نه اینکه همه مجوزها را به طور همزمان اعطا کنند. اسکریپت خود را طوری طراحی کنید که مجوزهای OAuth جزئی را مدیریت کند .

مشاهده محدوده‌ها

برای دیدن محدوده‌هایی که پروژه اسکریپت شما نیاز دارد:

1. پروژه اسکریپت را باز کنید.
2. در سمت چپ، روی نمای کلی کلیک کنید.
3. محدوده‌ها را در بخش محدوده‌های پروژه OAuth مشاهده کنید.

تنظیم محدوده‌های صریح

اسکریپت برنامه‌ها (Apps Script) با اسکن کد برای فراخوانی‌های تابع، به‌طور خودکار محدوده‌های مورد نیاز را تعیین می‌کند. اگرچه این برای اکثر اسکریپت‌ها کافی است، اما باید کنترل مستقیم‌تری برای افزونه‌های منتشر شده، برنامه‌های وب، برنامه‌های چت و فراخوانی‌های API چت اعمال کنید.

اسکریپت برنامه‌ها گاهی اوقات به طور خودکار محدوده‌های مجاز را اختصاص می‌دهد. این می‌تواند به این معنی باشد که اسکریپت شما از کاربران دسترسی بیشتری نسبت به نیاز خود درخواست می‌کند. برای اسکریپت‌های منتشر شده، محدوده‌های گسترده را با مجموعه‌ای محدود که نیازهای اسکریپت را پوشش می‌دهد، جایگزین کنید.

هشدار: همیشه از کمترین میزان مجاز برای مجموعه دامنه استفاده کنید. برای محافظت از اطلاعات کاربر، افزونه‌ها و سایر برنامه‌های منتشر شده نباید مجوزهای دامنه بیشتری از آنچه نیاز دارند درخواست کنند.

شما می‌توانید با ویرایش فایل مانیفست اسکریپت خود، محدوده‌هایی را که پروژه اسکریپت شما استفاده می‌کند، به طور صریح تنظیم کنید. فیلد مانیفست oauthScopes آرایه‌ای از محدوده‌هایی است که توسط پروژه استفاده می‌شود. برای تنظیم محدوده‌های پروژه خود:

1. پروژه اسکریپت را باز کنید.
2. در سمت چپ، روی پروژه کلیک کنید.
3. کادر انتخاب نمایش فایل مانیفست "appsscript.json" در ویرایشگر را علامت بزنید .
4. در سمت چپ، روی ویرایشگر کلیک کنید.
5. در سمت چپ، روی فایل appsscript.json کلیک کنید.
6. فیلد سطح بالا با برچسب oauthScopes را پیدا کنید. اگر وجود ندارد، می‌توانید آن را اضافه کنید.
7. محتویات آرایه oauthScopes را با محدوده‌هایی که می‌خواهید پروژه از آنها استفاده کند، جایگزین کنید. برای مثال:

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

8. در بالا، روی ذخیره ( کلیک کنید.

مدیریت مجوزهای OAuth به صورت جزئی

صفحه رضایت OAuth جزئی ابتدا برای کاربرانی که مستقیماً یک اسکریپت را اجرا می‌کنند، در Apps Script IDE راه‌اندازی شد. صفحه رضایت به تدریج در طول زمان برای سطوح دیگر، مانند ماکروها، تریگرها و افزونه‌ها، منتشر می‌شود. برای اطلاعات بیشتر، به بخش رضایت OAuth جزئی در اجراهای Google Apps Script IDE مراجعه کنید.

صفحه‌ی رضایت جزئی OAuth به کاربران اجازه می‌دهد تا مشخص کنند کدام حوزه‌های OAuth را مجاز کنند. این به کاربران کنترل دقیقی بر داده‌های حسابی که با هر اسکریپت به اشتراک می‌گذارند، می‌دهد. برای مثال، اگر یک اسکریپت حوزه‌های ایمیل و تقویم را درخواست کند، کاربران می‌توانند مجوز تقویم را اعطا کنند اما به Gmail این اجازه را ندهند.

بخش‌های بعدی نحوه مدیریت مجوزهای جزئی OAuth را شرح می‌دهند.

درخواست خودکار مجوز برای محدوده‌های لازم

اگر یک جریان اجرا به حوزه‌های خاصی نیاز داشته باشد، می‌توانید از کاربران بخواهید که آن مجوزها را اعطا کنند. اسکریپت شما می‌تواند مجوزها را بررسی کند و در صورت عدم وجود، به‌طور خودکار درخواست مجوز کند.

متدهای زیر از کلاس ScriptApp مجوزها را اعتبارسنجی کرده و اعلان مجوز را نمایش می‌دهند:

• requireScopes(authMode, oAuthScopes) : از این متد برای جریان‌هایی استفاده کنید که به حوزه‌های خاصی متکی هستند.
• requireAllScopes(authMode) : اگر جریان اجرا به تمام محدوده‌های پروژه وابسته است، از این متد استفاده کنید.

مثال

مثال زیر نحوه فراخوانی requireScopes() و requireAllScopes() را نشان می‌دهد. این اسکریپت از scopeهای مربوط به Gmail، Sheets و Calendar استفاده می‌کند. تابع sendEmail() فقط scopeهای مربوط به Gmail و Sheets را نیاز دارد در حالی که تابع createEventSendEmail() به تمام scopeهای استفاده شده توسط اسکریپت نیاز دارد.

// 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("[e-mail]", "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("[e-mail]", "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("[e-mail]", "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 حساس هستند زیرا امکان دسترسی به داده‌های کاربر گوگل را فراهم می‌کنند. اگر پروژه اسکریپت شما از حوزه‌هایی استفاده می‌کند که امکان دسترسی به داده‌های کاربر را فراهم می‌کنند، قبل از اینکه بتوانید آن را به صورت عمومی به عنوان یک برنامه وب یا افزونه منتشر کنید، پروژه باید از طریق تأیید کلاینت OAuth عبور کند. برای اطلاعات بیشتر، به راهنماهای زیر مراجعه کنید:

• تأیید کلاینت OAuth برای Apps Script
• برنامه‌های تأیید نشده
• سوالات متداول در مورد تأیید OAuth
• سرویس APIهای گوگل: سیاست داده‌های کاربر

دامنه‌های محدود

علاوه بر حوزه‌های حساس، حوزه‌های خاصی به عنوان محدود طبقه‌بندی می‌شوند و تابع قوانین اضافی هستند که به محافظت از داده‌های کاربر کمک می‌کنند. اگر برنامه‌ای منتشر می‌کنید که از حوزه‌های محدود استفاده می‌کند، باید با تمام مشخصات مطابقت داشته باشد.

قبل از انتشار، لیست کامل حوزه‌های محدود شده را بررسی کنید. برنامه‌های سازگار باید از الزامات اضافی برای حوزه‌های خاص API پیروی کنند.

در صورت امکان، برای ساده‌سازی فرآیند بررسی، از استفاده از محدوده‌های محدود خودداری کنید. می‌توانید از محدوده‌های محدود آزادانه برای برنامه‌های غیرعمومی استفاده کنید.