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

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

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

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

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

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

1. پروژه اسکریپت را باز کنید.
2. در سمت چپ، روی نمای کلی info_outline کلیک کنید.
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 یا Editor را منتشر کنید که از یک یا چند محدوده محدود استفاده می کند، افزونه قبل از انتشار باید با تمام محدودیت های مشخص شده مطابقت داشته باشد.

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

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

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

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

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

جیمیل

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

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

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

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

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

محدوده های چت گوگل

برای تماس با Chat API، باید به عنوان کاربر گپ Google یا برنامه Chat احراز هویت کنید. هر نوع احراز هویت به حوزه‌های متفاوتی نیاز دارد و همه روش‌های Chat API از احراز هویت برنامه پشتیبانی نمی‌کنند.

برای کسب اطلاعات بیشتر در مورد محدوده چت و انواع احراز هویت، به نمای کلی احراز هویت و مجوز Chat API مراجعه کنید.

جدول زیر روش‌ها و دامنه‌های Chat API پرکاربرد را بر اساس انواع احراز هویت پشتیبانی شده نشان می‌دهد:

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

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

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

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

در زیر نمونه ای از تنظیم یک نشانه دسترسی برای اجازه دسترسی به ابرداده پیام را نشان می دهد. تنها محدوده لازم برای این مثال 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 اغلب از آنها استفاده می کنند: