محدوده مجوز برای افزودنی های ویرایشگر

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

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

شما دامنه ها را در مانیفست خود با استفاده از رشته های URL اعلام می کنید. در طول جریان مجوز، Apps Script یک توصیف قابل خواندن توسط انسان از محدوده به کاربر ارائه می دهد. برای مثال، افزونه شما ممکن است از محدوده «خواندن سند جاری» استفاده کند که در مانیفست شما به‌عنوان https://www.googleapis.com/auth/documents.currentonly نوشته شده است. در طول جریان مجوز، افزونه‌ای با این محدوده از کاربر می‌خواهد که به این افزونه اجازه دهد: اسنادی را که این برنامه در آنها نصب شده است مشاهده و مدیریت کند.

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

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

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/script.container.ui",
       "https://www.googleapis.com/auth/spreadsheets"
     ],
     ...
   }
   

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

تأیید OAuth

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

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

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

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

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

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

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

هنگامی که یک افزونه ویرایشگر می‌سازید، دامنه‌های مورد نیاز توسط سرویس Apps Script و روش‌هایی که کد افزودنی استفاده می‌کند تعیین می‌شود. برای مثال، یک افزونه Sheets ممکن است به https://www.googleapis.com/auth/spreadsheets.readonly دامنه نیاز داشته باشد تا بتواند اطلاعات را از Google Sheets مختلف بخواند.

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

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

  /**
   * @OnlyCurrentDoc
   */

این نظر به Apps Script می‌گوید که دامنه فایل ویرایشگر را که روی currentonly تنظیم می‌کند محدود کند. به عنوان مثال، اگر این نظر را به فایل پروژه اسکریپت الحاقی Google Sheets اضافه کنید، مشخص می‌کنید که این افزونه فقط برای کارکرد در برگه فعلی باز نیاز به مجوز دارد و نه هر برگه دیگری که کاربر ممکن است در Google Drive داشته باشد. . برعکس، اگر افزونه Sheets شما نیاز به خواندن یا نوشتن داده‌ها در برگه‌ای دارد که کاربر در حال حاضر آن را باز نکرده است، نباید از این نظر استفاده کنید.

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