این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

محدوده مجوز

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

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

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

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

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

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

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

شما می‌توانید با انجام موارد زیر، محدوده‌هایی را که پروژه اسکریپت شما در حال حاضر به آنها نیاز دارد، مشاهده کنید:

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

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

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

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

شما می‌توانید با ویرایش فایل مانیفست ، حوزه‌هایی را که پروژه اسکریپت شما استفاده می‌کند، به طور صریح تنظیم کنید. فیلد 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 به کاربران کنترل دقیق‌تری بر داده‌های حسابی که می‌خواهند با هر اسکریپت به اشتراک بگذارند، می‌دهد. برای مثال، تصور کنید که اسکریپتی توسعه می‌دهید که درخواست مجوز برای حوزه‌های ایمیل و تقویم را دارد. کاربران شما ممکن است بخواهند از اسکریپت شما فقط برای قابلیت‌های آن با تقویم گوگل استفاده کنند، اما نه با جیمیل. با مجوزهای جزئی OAuth، کاربران می‌توانند فقط مجوز تقویم را اعطا کنند، اما نه جیمیل را.

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

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

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

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

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

مثال

مثال زیر نحوه فراخوانی متدهای requireScopes(authMode, oAuthScopes) و requireAllScopes(authMode) را نشان می‌دهد. این اسکریپت از 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("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 حساس هستند زیرا امکان دسترسی به داده‌های کاربر گوگل را فراهم می‌کنند. اگر پروژه اسکریپت شما از حوزه‌هایی استفاده می‌کند که امکان دسترسی به داده‌های کاربر را فراهم می‌کنند، قبل از اینکه بتوانید آن را به صورت عمومی به عنوان یک برنامه وب یا افزونه منتشر کنید، پروژه باید از طریق تأیید کلاینت OAuth عبور کند. برای اطلاعات بیشتر، به راهنماهای زیر مراجعه کنید:

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

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

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

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

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

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

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

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

مثال

یک تجربه سفارشی برای محدوده‌های از دست رفته ایجاد کنید

مثال

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

مثال

تأیید هویت OAuth

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

محدوده مجوز