محدوده، محدوده، محدوده

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

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

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

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

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

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

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

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

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

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

برای مثال، Apps Script ممکن است به طور پیش‌فرض به یک پروژه اسکریپت الحاقی دامنه بسیار مجاز https://mail.google.com بدهد. هنگامی که یک کاربر یک پروژه اسکریپت با این محدوده را مجوز می دهد، پروژه به حساب Gmail کاربر دسترسی کامل دارد. برای افزونه های منتشر شده، باید این محدوده را با مجموعه محدودتری جایگزین کنید که نیازهای افزونه ها را پوشش دهد و نه بیشتر.

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

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

1. دامنه‌هایی را که افزونه شما در حال حاضر استفاده می‌کند، مشاهده کنید . تعیین کنید که چه تغییراتی باید انجام شود، مانند استفاده از یک محدوده محدودتر.
2. فایل مانیفست افزونه خود را باز کنید .
3. فیلد سطح بالا با برچسب oauthScopes را پیدا کنید. اگر موجود نیست، می توانید آن را اضافه کنید.

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

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

5. تغییرات فایل مانیفست را ذخیره کنید.

تأیید OAuth

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

• تأیید مشتری OAuth برای Apps Script
• برنامه های تایید نشده
• سؤالات متداول تأیید OAuth
• سرویس Google APIs: خط مشی داده های کاربر

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

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

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

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

محدوده‌ها را برای افزونه‌های Google Workspace انتخاب کنید

بخش‌های زیر محدوده‌هایی را ارائه می‌کنند که معمولاً برای افزونه‌های Google Workspace استفاده می‌شوند.

دامنه ویرایشگر

در زیر دامنه‌های پرکاربرد برای افزونه‌های Google Workspace که اسناد، برگه‌ها و اسلایدها را گسترش می‌دهند، آمده است.

توجه: محدوده currentonly فقط در Apps Script Services در دسترس است. این شامل سرویس‌های پیشرفته اسکریپت برنامه‌ها یا تماس‌های مستقیم با APIهای Google Workspace نمی‌شود.

دامنه
دسترسی به فایل Docs فعلی	https://www.googleapis.com/auth/documents.currentonly اگر افزونه به Apps Script Docs API دسترسی داشته باشد، لازم است. اجازه دسترسی موقت به محتوای سند باز را می دهد.
دسترسی به فایل Sheets فعلی	https://www.googleapis.com/auth/spreadsheets.currentonly اگر افزونه به Apps Script Sheets API دسترسی داشته باشد، لازم است. اجازه دسترسی موقت به محتوای صفحه‌گسترده باز را می‌دهد.
دسترسی به فایل اسلایدهای فعلی	https://www.googleapis.com/auth/presentations.currentonly اگر افزونه به Apps Script Slides API دسترسی داشته باشد، لازم است. اجازه دسترسی موقت به محتوای ارائه باز را می دهد.
دسترسی به هر فایل	https://www.googleapis.com/auth/drive.file برای استفاده افزونه از onFileScopeGrantedTrigger و اگر افزونه به Docs، Sheets، Slides یا Drive API دسترسی داشته باشد، لازم است . با استفاده از سرویس درایو پیشرفته Apps Script به فایل‌های ایجاد شده یا بازشده توسط برنامه به هر فایل دسترسی می‌دهد. با این حال، این اجازه استفاده از اقدامات مشابه با استفاده از سرویس اصلی Drive را نمی دهد. مجوز فایل بر اساس هر فایل اعطا می شود و زمانی که کاربر مجوز برنامه را لغو می کند لغو می شود.

جیمیل

چند محدوده وجود دارد که به طور خاص برای افزونه های Google Workspace برای کمک به محافظت از داده های Gmail کاربر ایجاد شده است. شما باید این محدوده ها را به صراحت به مانیفست افزونه خود اضافه کنید ، همراه با هر کد دیگری که کد افزونه شما نیاز دارد.

در زیر دامنه‌های پرکاربرد برای افزونه‌های Google Workspace که Gmail را گسترش می‌دهند، آمده است. اگر برافزای شما Gmail را گسترش دهد، مواردی که دارای برچسب الزامی هستند باید به مانیفست افزونه Google Workspace شما اضافه شوند.

همچنین مطمئن شوید که دامنه بسیار گسترده https://mail.google.com را در برافزای خود با مجموعه‌ای از دامنه‌های محدودتر جایگزین کنید که امکان تعاملات مورد نیاز افزونه شما را فراهم می‌کند و نه بیشتر.

دامنه
پیش نویس های جدید ایجاد کنید	https://www.googleapis.com/auth/gmail.addons.current.action.compose اگر افزونه از راه‌اندازهای اقدام نوشتن استفاده می‌کند، الزامی است. به افزونه اجازه می دهد تا به طور موقت پیام ها و پاسخ های پیش نویس جدید ایجاد کند. برای جزئیات بیشتر به نوشتن پیام های پیش نویس مراجعه کنید. این محدوده همچنین اغلب با اقدامات ترکیبی استفاده می شود. به یک نشانه دسترسی نیاز دارد.
فراداده پیام باز را بخوانید	https://www.googleapis.com/auth/gmail.addons.current.message.metadata اجازه دسترسی موقت به فراداده پیام باز (مانند موضوع یا گیرندگان) را می دهد. اجازه خواندن محتوای پیام را نمی دهد و به یک نشانه دسترسی نیاز دارد. اگر افزونه از فراداده در راه‌اندازهای اقدام نوشتن استفاده می‌کند، الزامی است. برای کنش‌های نوشتن ، اگر راه‌انداز نوشتن نیاز به دسترسی به ابرداده داشته باشد، این محدوده مورد نیاز است. در عمل، این محدوده به یک راه‌انداز نوشتن اجازه می‌دهد به فهرست‌های گیرنده (به:، cc:، و bcc:) از پیش‌نویس ایمیل پاسخ دسترسی پیدا کند.
محتوای پیام باز را بخوانید	https://www.googleapis.com/auth/gmail.addons.current.message.action پس از تعامل کاربر، مانند زمانی که یک آیتم منوی افزودنی انتخاب می شود، به محتوای پیام باز اجازه دسترسی می دهد. به یک نشانه دسترسی نیاز دارد.
مطالب تاپیک باز را بخوانید	https://www.googleapis.com/auth/gmail.addons.current.message.readonly اجازه دسترسی موقت به فراداده و محتوای پیام باز را می دهد. همچنین به محتوای پیام‌های دیگر در موضوع باز اجازه دسترسی می‌دهد. به یک نشانه دسترسی نیاز دارد.
هر گونه محتوای پیام و ابرداده را بخوانید	https://www.googleapis.com/auth/gmail.readonly هر گونه فراداده و محتوای ایمیل، از جمله پیام باز را بخوانید. در صورت نیاز به خواندن اطلاعات مربوط به سایر پیام‌ها، مانند هنگام انجام یک درخواست جستجو یا خواندن کل رشته ایمیل، ضروری است. هشدار : این یک محدوده بسیار گسترده و محدود است. فقط در صورت لزوم از آن استفاده کنید.

دامنه های تقویم گوگل

در زیر دامنه‌های پرکاربرد برای افزونه‌های Google Workspace که تقویم Google را گسترش می‌دهند، آمده است.

دامنه
دسترسی به ابرداده رویداد	https://www.googleapis.com/auth/calendar.addons.execute اگر افزونه به فراداده رویداد تقویم دسترسی داشته باشد، ضروری است. به افزونه اجازه می دهد تا به فراداده رویداد دسترسی داشته باشد.
داده های رویداد تولید شده توسط کاربر را بخوانید	https://www.googleapis.com/auth/calendar.addons.current.event.read اگر افزونه نیاز به خواندن داده های رویداد ایجاد شده توسط کاربر داشته باشد، ضروری است. به افزونه اجازه می‌دهد به داده‌های رویداد تولید شده توسط کاربر دسترسی داشته باشد. این داده ها فقط در صورتی در دسترس هستند که فیلد مانیفست addOns.calendar.eventAccess روی READ یا READ_WRITE تنظیم شده باشد.
داده های رویداد تولید شده توسط کاربر را بنویسید	https://www.googleapis.com/auth/calendar.addons.current.event.write اگر افزونه نیاز به نوشتن داده های رویداد تولید شده توسط کاربر داشته باشد، لازم است. به افزونه اجازه می‌دهد تا داده‌های رویداد تولید شده توسط کاربر را ویرایش کند. این داده ها تنها در صورتی در دسترس هستند که فیلد مانیفست addOns.calendar.eventAccess روی WRITE یا READ_WRITE تنظیم شده باشد.

محدوده های گوگل درایو

در زیر دامنه‌های پرکاربرد افزونه‌های Google Workspace که Google Drive را گسترش می‌دهند، آمده است.

دامنه
فراداده مورد انتخابی را بخوانید	https://www.googleapis.com/auth/drive.addons.metadata.readonly اگر افزونه یک رابط متنی را اجرا کند که هنگام انتخاب موارد در Drive توسط کاربر فعال می شود، لازم است. به افزونه اجازه می‌دهد تا فراداده محدودی را درباره مواردی که کاربر در Google Drive انتخاب کرده است بخواند. فراداده به شناسه، عنوان، نوع MIME، نشانی اینترنتی نماد و اینکه آیا افزونه مجوز دسترسی به مورد را دارد یا خیر، محدود می‌شود.
دسترسی به هر فایل	https://www.googleapis.com/auth/drive.file اگر افزونه نیاز به دسترسی به فایل‌های Drive جداگانه داشته باشد، توصیه می‌شود. با استفاده از سرویس درایو پیشرفته Apps Script به فایل‌های ایجاد شده یا بازشده توسط برنامه به هر فایل دسترسی می‌دهد. با این حال، این اجازه استفاده از اقدامات مشابه با استفاده از سرویس اصلی Drive را نمی دهد. مجوز فایل بر اساس هر فایل اعطا می شود و زمانی که کاربر مجوز برنامه را لغو می کند لغو می شود. به مثال درخواست دسترسی به فایل برای فایل های انتخابی مراجعه کنید.

دسترسی به توکن ها

برای محافظت از داده‌های کاربر، دامنه‌های Gmail مورد استفاده در افزونه‌های Google Workspace فقط به داده‌های کاربر دسترسی موقت می‌دهد. برای فعال کردن دسترسی موقت، باید تابع GmailApp.setCurrentMessageAccessToken(accessToken) با استفاده از یک نشانه دسترسی به عنوان آرگومان فراخوانی کنید. شما باید یک نشانه دسترسی از یک شی رویداد اقدام دریافت کنید.

توجه: نشانه دسترسی که دامنه‌های Gmail را فعال می‌کند با نشانه دسترسی بازگردانده شده توسط ScriptApp.getOAuthToken() یکسان نیست . شما باید از نشانه ارائه شده در شیء رویداد اکشن استفاده کنید.

در زیر نمونه ای از تنظیم یک نشانه دسترسی برای اجازه دسترسی به ابرداده پیام را نشان می دهد. تنها محدوده لازم برای این مثال https://www.googleapis.com/auth/gmail.addons.current.message.metadata است.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

سایر حوزه های Google Workspace

اگر افزونه شما از سایر سرویس‌های Google Workspace یا Apps Script استفاده می‌کند، ممکن است به محدوده‌های بیشتری نیاز داشته باشد. در بیشتر موارد می‌توانید به Apps Script اجازه دهید این محدوده‌ها را شناسایی کند و مانیفست را به‌طور خودکار به‌روزرسانی کند. هنگام ویرایش فهرست محدوده مانیفست خود، هیچ محدوده ای را حذف نکنید، مگر اینکه آنها را با جایگزین مناسب تری جایگزین کنید، مانند یک محدوده باریک تر.

جدول زیر فهرستی از حوزه‌هایی را نشان می‌دهد که افزونه‌های Google Workspace اغلب استفاده می‌کنند:

دامنه
آدرس ایمیل کاربر را بخوانید	https://www.googleapis.com/auth/userinfo.email به پروژه اجازه می دهد تا آدرس ایمیل کاربر فعلی را بخواند.
اجازه تماس با سرویس های خارجی	https://www.googleapis.com/auth/script.external_request به پروژه اجازه می دهد تا درخواست های UrlFetch را ایجاد کند. اگر پروژه از کتابخانه OAuth2 for Apps Script استفاده کند، این مورد نیز لازم است.
منطقه محلی و منطقه زمانی کاربر را بخوانید	https://www.googleapis.com/auth/script.locale به پروژه اجازه می دهد تا منطقه محلی و منطقه زمانی کاربر فعلی را بیاموزد. برای جزئیات به دسترسی به منطقه محلی کاربر و منطقه زمانی مراجعه کنید.
ایجاد محرک	https://www.googleapis.com/auth/script.scriptapp به پروژه اجازه می دهد تا محرک ایجاد کند.
پیش نمایش لینک های شخص ثالث	https://www.googleapis.com/auth/workspace.linkpreview اگر افزونه پیوندهای یک سرویس شخص ثالث را پیش‌نمایش کند، ضروری است. به پروژه اجازه می‌دهد تا زمانی که کاربر با آن در حال تعامل است، پیوندی را در یک برنامه Google Workspace ببیند. برای کسب اطلاعات بیشتر، پیش نمایش پیوندها با تراشه های هوشمند را ببینید.
منابع شخص ثالث ایجاد کنید	https://www.googleapis.com/auth/workspace.linkcreate اگر افزونه منابعی را در یک سرویس شخص ثالث ایجاد کند، لازم است. به پروژه اجازه می‌دهد اطلاعاتی را که کاربران در فرم ایجاد منبع ارسال می‌کنند بخواند و پیوندی به منبع در برنامه Google Workspace درج کند. برای کسب اطلاعات بیشتر، به ایجاد منابع شخص ثالث از منوی @ مراجعه کنید.