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