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

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

در طول این جریان، اعلان به کاربر می‌گوید که برنامه برای انجام چه کاری مجوز می‌خواهد. برای مثال، یک افزونه ممکن است مجوز خواندن پیام ایمیل کاربر یا ایجاد رویداد در تقویم او را بخواهد. پروژه اسکریپت افزونه، این مجوزهای فردی را به عنوان دامنه‌های 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 ممکن است به طور پیش‌فرض به یک پروژه اسکریپت افزونه، دامنه بسیار مجاز 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 که Docs، Sheets و Slides را گسترش می‌دهند، آورده شده است.

جیمیل

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

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

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

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

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

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

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

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

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

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

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

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

برای محافظت از داده‌های کاربر، محدوده‌های Gmail مورد استفاده در افزونه‌های Google Workspace فقط دسترسی موقت به داده‌های کاربر را اعطا می‌کنند. برای فعال کردن دسترسی موقت، باید تابع GmailApp.setCurrentMessageAccessToken(accessToken) را با استفاده از یک توکن دسترسی به عنوان آرگومان فراخوانی کنید. باید یک توکن دسترسی را از یک شیء رویداد 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 اغلب از آنها استفاده می‌کنند: