اسکریپت برنامههای گوگل برای دسترسی به دادههای خصوصی از سرویسهای داخلی گوگل یا سرویسهای پیشرفته گوگل، به مجوز کاربر نیاز دارد.
نحوهی عملکرد مجوز برای سرویسهای گوگل
وقتی یک اسکریپت نیاز به دسترسی به سرویسهای گوگل دارد، از این فرآیند کلی پیروی میکند:
- تشخیص : Apps Script اسکریپت را اسکن میکند تا مشخص کند از چه سرویسهایی استفاده میکند (برای مثال،
SpreadsheetAppیاGmailApp). - تعیین محدوده : بر اساس اسکن، Apps Script مجموعهای از محدودههای OAuth مورد نیاز برای اجرای اسکریپت را شناسایی میکند.
- بررسی مجوز : وقتی اسکریپت اجرا میشود، بررسی میکند که آیا کاربر قبلاً آن محدودهها را مجاز کرده است یا خیر.
- اعلان کاربر : اگر مجوز وجود نداشته باشد، پنجرهای ظاهر میشود که از کاربر میخواهد مجوز را اعطا کند.
- اجرا : پس از اینکه اسکریپت مجاز شد، میتواند به دادههای درخواستی برای آن کاربر دسترسی پیدا کند.
مجوزها و انواع اسکریپتها
هویت کاربری که یک اسکریپت با آن اجرا میشود - و بنابراین دادههایی که میتواند به آنها دسترسی داشته باشد - بسته به سناریویی که اسکریپت در آن اجرا میشود، متفاوت است، همانطور که در جدول زیر نشان داده شده است.
| نوع اسکریپت | اسکریپت به صورت ... اجرا میشود. |
|---|---|
| مستقل ، افزونهی Google Workspace ، یا متصل به Google Docs، Google Sheets، Google Slides یا Google Forms | کاربر پشت کیبورد |
| تابع سفارشی در یک صفحه گسترده | کاربر ناشناس ؛ با این حال، محدودیتهای سهمیهبندی علیه کاربر در صفحه کلید محاسبه میشود. |
| ابزارک وب اپلیکیشن یا سایتهای گوگل | کاربر در صفحه کلید یا مالک اسکریپت، بسته به گزینههای انتخاب شده هنگام استقرار برنامه |
| ماشه قابل نصب | کاربری که تریگر را ایجاد کرده است |
اعطای حقوق دسترسی
Apps Script بر اساس اسکن کد، محدودههای مجوز (مانند دسترسی به فایلهای Sheets یا Gmail شما) را به طور خودکار تعیین میکند. کدی که کامنتگذاری شده است، همچنان میتواند درخواست مجوز ایجاد کند. اگر اسکریپتی نیاز به مجوز داشته باشد، هنگام اجرا، یک کادر محاورهای مجوز ظاهر میشود.
اسکریپتهایی که قبلاً مجاز کردهاید، در صورت اضافه شدن سرویسهای جدید توسط تغییر کد، درخواست مجوز اضافی نیز میکنند. اگر به عنوان یک برنامه وب که تحت هویت کاربری مالک اسکریپت اجرا میشود، به اسکریپتها دسترسی پیدا کنید، ممکن است درخواست مجوز نکنند.
لغو حقوق دسترسی
برای لغو دسترسی یک اسکریپت به دادههایتان، این مراحل را دنبال کنید:
- به بخش امنیت حساب گوگل خود مراجعه کنید.
- در بخش «اتصالات شما به برنامهها و سرویسهای شخص ثالث» ، روی «مشاهده همه اتصالات» کلیک کنید.
- اسکریپت یا برنامهای را که میخواهید دسترسی آن را لغو کنید، انتخاب کنید.
- روی حذف تمام اتصالاتی که با APP_NAME دارید کلیک کنید، سپس روی تأیید کلیک کنید.
محدود کردن دامنه به سند فعلی
اگر در حال ساخت افزونه یا اسکریپت دیگری هستید که از سرویس Spreadsheet ، سرویس Document ، سرویس Slides یا سرویس Forms استفاده میکند، میتوانید پنجرهی مجوزدهی را طوری تنظیم کنید که فقط دسترسی به فایلهایی را که افزونه یا اسکریپت در آنها استفاده شده است، درخواست کند، نه دسترسی به تمام صفحات گسترده، اسناد یا فرمهای کاربر. برای انجام این کار، حاشیهنویسی JSDoc زیر را در یک کامنت در سطح فایل قرار دهید:
/**
* @OnlyCurrentDoc
*/
یک حاشیهنویسی متضاد، @NotOnlyCurrentDoc ، در صورتی در دسترس است که اسکریپت شما شامل کتابخانهای باشد که @OnlyCurrentDoc را تعریف میکند، اما اسکریپت اصلی در واقع به دسترسی به چیزی بیش از فایل فعلی نیاز دارد.
چرخه عمر مجوز برای افزونهها
افزونههای Sheets، Docs، Slides و Forms عموماً از همان مدل مجوزدهی اسکریپتهایی که به یک سند متصل هستند، پیروی میکنند. با این حال، در شرایط خاص، توابع onOpen(e) و onEdit(e) آنها در حالت بدون مجوز اجرا میشوند که پیچیدگیهای بیشتری را ایجاد میکند. برای اطلاعات بیشتر، به راهنمای چرخه عمر مجوزدهی افزونهها مراجعه کنید.
محدودیتهای کاربر برنامه OAuth
برنامههایی که از OAuth برای دسترسی به دادههای کاربر گوگل استفاده میکنند، از جمله پروژههای Apps Script، مشمول محدودیتهای مجوز هستند. برای جزئیات بیشتر به محدودیتهای کاربر برنامه OAuth مراجعه کنید.
رفتار احراز هویت مجدد با Apps Script
Apps Script فرکانس احراز هویت مجدد را که در تنظیمات سرویس Google Cloud پیکربندی شده است، اعمال نمیکند. دلیل این امر این است که Apps Script میتواند به طور خودکار با استفاده از triggerها اجرا شود، که بدون تعامل مستقیم کاربر عمل میکنند. این اجراهای خودکار، درخواستهای احراز هویت مجدد را فعال نمیکنند. برنامه Apps Script شما به طور خودکار از شما نمیخواهد که پس از مدت زمان مشخص شده (مثلاً ۱۲ ساعت) دوباره احراز هویت کنید.
تعیین محدودههای صریح در مانیفست
Apps Script با اسکن کد برای فراخوانی توابع، به طور خودکار محدودههای مورد نیاز را تعیین میکند. اگر به کنترل بیشتری نیاز دارید، میتوانید محدودهها را به طور صریح در مانیفست پروژه ( appsscript.json ) تنظیم کنید. این کار برای اسکریپتهای منتشر شده توصیه میشود تا اطمینان حاصل شود که از حداقل مجوزهای مورد نیاز استفاده میکنید.
برای دستورالعملها، به تنظیم محدودههای صریح مراجعه کنید.
عیبیابی
- خطای "نیاز به مجوز" هنگام اجرای یک تریگر : تریگرها باید توسط کاربری که آنها را ایجاد کرده است، مجاز شوند. اگر کدی اضافه کنید که به مجوزهای جدید نیاز دارد، باید یک بار به صورت دستی یک تابع را در ویرایشگر اسکریپت اجرا کنید تا پنجره مجوز فعال شود.
- بهروزرسانی نشدن دامنهها : اگر کد خود را بهروزرسانی کردهاید اما پنجرهی تأیید مجوز تغییرات را نشان نمیدهد، پروژه را ذخیره کرده و ویرایشگر را بهروزرسانی کنید. اگر از دامنههای صریح در مانیفست استفاده میکنید، مطمئن شوید که دامنهی جدید را به آرایهی
oauthScopesاضافه کردهاید. - هشدار «این برنامه مسدود شده است» یا برنامه تأیید نشده : این اتفاق زمانی رخ میدهد که اسکریپت شما از حوزههای حساس یا محدود استفاده میکند و توسط گوگل تأیید نشده است. به تأیید کلاینت OAuth مراجعه کنید.