محدوده مجوز

bookmark_border با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

کاربران باید پروژه های اسکریپتی را که به داده های آنها دسترسی دارند یا از طرف آنها عمل می کنند مجوز دهند. هنگامی که کاربر برای اولین بار اسکریپتی را اجرا می کند که نیاز به مجوز دارد، UI یک اعلان برای شروع جریان مجوز ارائه می دهد.

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

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

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

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

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

مشاهده دامنه ها

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

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

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

Apps Script به طور خودکار تعیین می کند که یک اسکریپت با اسکن کد آن برای فراخوانی های تابعی که به آنها نیاز دارد، به چه محدوده هایی نیاز دارد. برای بیشتر اسکریپت‌ها این کافی است و در وقت شما صرفه‌جویی می‌کند، اما برای افزونه‌های منتشر شده، برنامه‌های وب، برنامه‌های چت Google و تماس‌های Google Chat API باید کنترل مستقیم بیشتری بر دامنه‌ها اعمال کنید.

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

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

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

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

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

مجوزهای OAuth گرانول را مدیریت کنید

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

بخش‌های زیر روش‌های اصلی مدیریت مجوزهای OAuth گرانول را شرح می‌دهند.

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

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

روش‌های زیر از کلاس ScriptApp به شما امکان می‌دهند مجوز را برای حوزه‌های مورد نیاز تأیید کنید و به طور خودکار درخواست مجوز را برای درخواست مجوزهای از دست رفته ارائه دهید:

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

مثال

مثال زیر نحوه فراخوانی متدهای requireScopes(authMode, oAuthScopes) و requireAllScopes(authMode) را نشان می دهد. این اسکریپت از دامنه‌های Gmail، Sheets و Calendar استفاده می‌کند. تابع 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...
}

اطمینان حاصل کنید که اجرای ماشه دارای مجوز است

عملکردهای مرتبط با محرک‌ها می‌توانند به طور خودکار در رویدادهای خاص اجرا شوند و کاربر ممکن است برای ارائه مجوزهای بیشتر حضور نداشته باشد. توصیه می‌کنیم قبل از نصب تریگر، از 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 APIs: خط مشی داده های کاربر

محدوده های محدود

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

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