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

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

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

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

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

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

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

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

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

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

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

برای مثال، 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
• سرویس APIهای گوگل: سیاست داده‌های کاربر

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

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

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

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

افزونه‌ی ابزارهای توسعه‌دهندگان Google Workspace برای ویژوال استودیو کد، اطلاعات تشخیصی برای تمام حوزه‌ها، از جمله توضیحات حوزه و اینکه آیا حساس یا محدود است، ارائه می‌دهد.

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

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

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

محدوده‌های پرکاربرد زیر برای افزونه‌های Google Workspace، Google Docs، Google Sheets و Google Slides را گسترش می‌دهند.

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

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

جیمیل

محدوده‌هایی (scope) وجود دارند که به‌طور خاص برای افزونه‌های Google Workspace ایجاد شده‌اند تا به محافظت از داده‌های Gmail کاربر کمک کنند. این محدوده‌ها را به همراه سایر موارد مورد نیاز، صریحاً به مانیفست افزونه خود اضافه کنید.

جدول زیر فهرستی از محدوده‌های پرکاربرد افزونه‌های Google Workspace که Gmail را گسترش می‌دهند، ارائه می‌دهد. اگر افزونه شما Gmail را گسترش می‌دهد، باید محدوده‌هایی را که با برچسب «الزامی» مشخص شده‌اند به مانیفست افزونه Google Workspace خود اضافه کنید.

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

محدوده
ایجاد پیش‌نویس‌های جدید	https://www.googleapis.com/auth/gmail.addons.current.action.compose در صورتی که افزونه از محرک‌های عمل نوشتن استفاده کند، الزامی است. به افزونه اجازه می‌دهد تا به‌طور موقت پیام‌ها و پاسخ‌های پیش‌نویس جدید ایجاد کند. برای جزئیات بیشتر به بخش نوشتن پیام‌های پیش‌نویس مراجعه کنید؛ این محدوده اغلب با [compose actions] (/workspace/add-ons/gmail/extending-compose-ui) استفاده می‌شود. به یک توکن دسترسی نیاز دارد.
خواندن فراداده پیام باز	https://www.googleapis.com/auth/gmail.addons.current.message.metadata دسترسی موقت به فراداده‌های پیام باز (مانند موضوع یا گیرندگان) را اعطا می‌کند. اجازه خواندن محتوای پیام را نمی‌دهد و به یک توکن دسترسی نیاز دارد. اگر افزونه از فراداده در تریگرهای عمل نوشتن استفاده کند، الزامی است. برای اعمال نوشتن ، این دامنه در صورتی الزامی است که تریگر نوشتن نیاز به دسترسی به فراداده داشته باشد. در عمل، این دامنه به تریگر نوشتن اجازه می‌دهد به فهرست‌های گیرنده (to:، 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 که تقویم گوگل را گسترش می‌دهند، ارائه می‌دهد.

محدوده
دسترسی به فراداده رویداد	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 تنظیم شده باشد.

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

برای فراخوانی API چت گوگل، به عنوان کاربر چت گوگل یا به عنوان برنامه چت گوگل احراز هویت کنید. هر نوع احراز هویت به حوزه‌های مختلفی نیاز دارد و همه متدهای API چت از احراز هویت برنامه پشتیبانی نمی‌کنند.

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

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

روش	احراز هویت کاربر پشتیبانی می‌شود	احراز هویت برنامه پشتیبانی می‌شود	دامنه‌های مجوز پشتیبانی می‌شوند
ارسال پیام			با احراز هویت کاربر : chat.messages.create chat.messages chat.import با احراز هویت برنامه : chat.bot
ایجاد یک فضا			با احراز هویت کاربر : chat.spaces.create chat.spaces chat.import با احراز هویت برنامه و تأیید مدیر (موجود در پیش‌نمایش توسعه‌دهندگان ): chat.app.spaces.create chat.app.spaces
ایجاد و اضافه کردن اعضا به یک فضا		—	با احراز هویت کاربر : chat.spaces.create chat.spaces
اضافه کردن کاربر به یک فضا			با احراز هویت کاربر : chat.memberships chat.memberships.app chat.import با احراز هویت برنامه و تأیید مدیر (موجود در پیش‌نمایش توسعه‌دهندگان ): chat.app.memberships
فهرست کردن فعالیت‌ها یا رویدادها از یک فضای چت		—	با احراز هویت کاربر ، باید برای هر نوع رویداد موجود در درخواست، از یک محدوده استفاده کنید: برای رویدادهای مربوط به پیام‌ها: chat.messages chat.messages.readonly برای رویدادهای مربوط به واکنش‌ها: chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly برای رویدادهای مربوط به عضویت‌ها: chat.memberships chat.memberships.readonly برای رویدادهای مربوط به فضا: chat.spaces chat.spaces.readonly

دامنه‌های گوگل درایو

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

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

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

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

توکن دسترسی که محدوده‌های Gmail را فعال می‌کند با توکن دسترسی که توسط ScriptApp.getOAuthToken برگردانده می‌شود، یکسان نیست. از توکن ارائه شده در شیء رویداد action استفاده کنید.

در ادامه مثالی از تنظیم توکن دسترسی برای دسترسی به فراداده‌های یک پیام نشان داده شده است. تنها محدوده مورد نیاز برای این مثال 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 یا 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 به پروژه اجازه می‌دهد تا triggerها را ایجاد کند.
پیش‌نمایش لینک‌های شخص ثالث	https://www.googleapis.com/auth/workspace.linkpreview در صورتی که افزونه، لینک‌های یک سرویس شخص ثالث را پیش‌نمایش کند، الزامی است. به پروژه اجازه می‌دهد تا در حین تعامل کاربر با یک لینک، آن را در برنامه Google Workspace مشاهده کند. برای کسب اطلاعات بیشتر، به پیش‌نمایش لینک‌ها با تراشه‌های هوشمند مراجعه کنید.
ایجاد منابع شخص ثالث	https://www.googleapis.com/auth/workspace.linkcreate در صورتی که افزونه منابعی را در یک سرویس شخص ثالث ایجاد کند، الزامی است. به پروژه اجازه می‌دهد اطلاعاتی را که کاربران به فرم ایجاد منبع ارسال می‌کنند، بخواند و پیوندی به منبع را در یک برنامه Google Workspace درج کند. برای کسب اطلاعات بیشتر، به «ایجاد منابع شخص ثالث» از منوی @ مراجعه کنید.