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

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

مدل مجوز برای افزودنی های ویرایشگر به چند دلیل پیچیده تر است:

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

• این افزونه‌ها روی فایل‌هایی در Google Drive کار می‌کنند که می‌توانند با همکاران به اشتراک گذاشته شوند. همکارانی که افزونه ویرایشگر را نصب نکرده‌اند، آن را در اسنادی می‌بینند که سازنده فایل از آن استفاده کرده است.

• وقتی یک سند باز می شود، افزودنی های ویرایشگر به طور خودکار توابع onOpen() خود را اجرا می کنند.

برای محافظت از داده‌های کاربر، حالت‌های مجوز اعمال می‌شود که برخی از سرویس‌ها را برای onOpen() از دسترس خارج می‌کند. این راهنما می تواند به شما کمک کند تا بفهمید کد شما چه کاری و چه زمانی می تواند انجام دهد.

مدل مجوز

حالت مجوز یک افزونه ویرایشگر به وضعیت آن بستگی دارد، که بستگی به این دارد که چه کسی از آن استفاده می کند: کاربری که افزونه را نصب کرده است یا یک همکار.

حالت های افزودنی ویرایشگر

افزونه های ویرایشگر در منوی افزونه ها نصب، فعال یا هر دو هستند.

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

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

	نصب شده است	فعال شد
اعمال می شود	کاربر	سند، فرم، ارائه یا صفحه گسترده
ناشی از	دریافت افزونه از فروشگاه	دریافت افزونه از فروشگاه هنگام استفاده از آن سند، فرم، ارائه یا صفحه گسترده یا استفاده از افزونه ای که قبلاً در آن سند، فرم، ارائه یا صفحه گسترده نصب شده است
منو قابل مشاهده برای	فقط آن کاربر در تمام اسناد، فرم‌ها، ارائه‌ها یا صفحه‌گسترده‌هایی که باز یا ایجاد می‌کنند	همه همکاران در آن سند، فرم، ارائه یا صفحه گسترده
حالت مجوز برای onOpen()	AuthMode.NONE (مگر اینکه فعال باشد، در این صورت AuthMode.LIMITED)	AuthMode.LIMITED

حالت های مجوز

وقتی کاربر یک سند، فرم، ارائه یا صفحه گسترده را باز می کند، تابع onOpen() یک افزونه ویرایشگر به طور خودکار اجرا می شود. برای محافظت از داده‌های کاربران، Apps Script کاری را که تابع onOpen() می‌تواند انجام دهد، محدود می‌کند. حالت افزودنی ویرایشگر تعیین می‌کند که تابع onOpen() در کدام حالت مجوز اجرا شود.

اگر افزونه ویرایشگر در فایل، فرم، ارائه یا صفحه گسترده فعال باشد، onOpen() در AuthMode.LIMITED اجرا می شود. اگر افزونه فعال نباشد و فقط نصب شده باشد، onOpen() در AuthMode.NONE اجرا می شود.

در AuthMode.NONE ، یک افزونه نمی‌تواند خدمات خاصی را اجرا کند تا زمانی که کاربر با کلیک کردن یا اجرای توابع سفارشی با افزونه تعامل داشته باشد. اگر افزونه شما سعی کند از این سرویس ها در onOpen() ، onInstall() یا دامنه جهانی استفاده کند، مجوزها از کار می افتد و سایر تماس ها، مانند پر کردن منوها، متوقف می شوند . راهنما تنها گزینه پشتیبانی شده است.

برای اجرای تماس های سرویس محدود، باید از حالت مجوز AuthMode.FULL استفاده کنید. عملکردهای تعامل کاربر، مانند کلیک کردن روی گزینه منو، فقط در این حالت اجرا می شود. پس از اجرای کد در حالت AuthMode.FULL ، افزونه می تواند از تمام محدوده هایی که کاربر مجاز کرده است استفاده کند.

توجه: فقط افزونه های ویرایشگر منتشر شده می توانند در AuthMode.NONE باشند. افزونه‌های ویرایش‌نشده منتشر نشده onOpen() در AuthMode.LIMITED اجرا می‌شوند. با این حال، می‌توانید یک افزونه ویرایشگر را آزمایش کنید تا تأیید کنید که یک افزونه در حال توسعه در هر یک از حالت‌های مجوز مطابق با مدنظر عمل می‌کند.

Apps Script حالت مجوز را به عنوان ویژگی authMode پارامتر رویداد Apps Script، e ; مقدار e.authMode مربوط به یک ثابت در فهرست Apps Script ScriptApp.AuthMode است.

حالت‌های مجوز برای همه روش‌های اجرای Apps Script اعمال می‌شود، از جمله اجرا از ویرایشگر اسکریپت، از یک آیتم منو، یا از تماس google.script.run Apps Script. با این حال، ویژگی e.authMode فقط در صورتی قابل بررسی است که اسکریپت در نتیجه یک تریگر مانند onOpen() ، onEdit() یا onInstall() اجرا شود. توابع سفارشی در کاربرگ‌نگار Google از حالت مجوز خود استفاده می‌کنند، AuthMode.CUSTOM_FUNCTION ، که مشابه LIMITED است اما محدودیت‌های کمی متفاوت دارد. برای همه موارد دیگر، اسکریپت ها در AuthMode.FULL اجرا می شوند، همانطور که در جدول زیر توضیح داده شده است.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
رخ می دهد برای	onOpen() (اگر کاربر افزونه ای را نصب کرده باشد اما آن را در سند، فرم، ارائه یا صفحه گسترده فعال نکرده باشد)	onOpen() (همه زمان‌های دیگر) onEdit() (فقط در Sheets)	توابع سفارشی	همه زمان های دیگر، از جمله: ماشه های قابل نصب onInstall() google.script.run
دسترسی به اطلاعات کاربر	فقط محلی	فقط محلی	فقط محلی	آره
دسترسی به سند، فرم، ارائه یا صفحه گسترده	خیر	آره	بله - فقط خواندنی	آره
دسترسی به رابط کاربری	افزودن آیتم های منو	افزودن آیتم های منو	خیر	آره
دسترسی به Properties	خیر	آره	آره	آره
دسترسی به Jdbc ، UrlFetch	خیر	خیر	آره	آره
سایر خدمات	Logger Utilities	هر سرویسی که به داده های کاربر دسترسی ندارد	هر سرویسی که به داده های کاربر دسترسی ندارد	کلیه خدمات

چرخه عمر مجوز یک افزونه ویرایشگر

هنگامی که یک افزونه برای کاربر فعلی نصب می شود یا در فایل فعلی فعال می شود، با باز شدن آن فایل، برافزا برای سند، فرم، ارائه یا صفحه گسترده بارگیری می شود. این افزونه در منوی Extensions فهرست شده است و شروع به گوش دادن به محرک های ساده onInstall() , onOpen() و onEdit() می کند. اگر کاربر روی آیتم منوی Extensions کلیک کند، اجرا می شود .

افزونه ویرایشگر نصب شده است

هنگامی که یک افزونه ویرایشگر از فروشگاه نصب می شود، تابع onInstall() آن در AuthMode.FULL اجرا می شود. در این حالت مجوز، افزونه می‌تواند یک روال تنظیم پیچیده را اجرا کند. همچنین باید از onInstall() برای ایجاد آیتم های منو استفاده کنید، زیرا سند، فرم، ارائه یا صفحه گسترده از قبل باز است و تابع onOpen() شما اجرا نشده است. نمونه زیر نحوه فراخوانی تابع onOpen() از تابع onInstall() را نشان می دهد:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

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

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

اگر یک افزونه فقط یک منوی اصلی ایجاد کند، حالت مهم نیست. نمونه زیر یک تابع اصلی onOpen() را نشان می دهد:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

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

نمونه زیر یک onOpen() پیشرفته را نشان می دهد که عملکرد خود را بر اساس حالت مجوز تغییر می دهد:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

اخطار: وقتی تابع onOpen() اجرا می شود، کل اسکریپت بارگیری می شود و تمام عبارات جهانی همگی تحت همان حالت مجوز اجرا می شوند که onOpen() . اگر حالت مجوز، عبارات جهانی را ممنوع کند، هم دستورات جهانی و هم onOpen() اجرا نمی شوند. اگر افزونه منتشر شده نتوانست آیتم های منوی خود را اضافه کند، کنسول جاوا اسکریپت مرورگر را بررسی کنید تا ببینید آیا خطایی برگردانده شده است. سپس، اسکریپت خود را بررسی کنید تا ببینید آیا تابع onOpen() یا متغیرهای سراسری خدماتی را که در AuthMode.NONE مجاز نیستند فراخوانی می‌کنند.

توجه داشته باشید که افزونه‌ها نمی‌توانند هنگام اجرا در AuthMode.LIMITED ، نوارهای کناری یا دیالوگ‌ها را باز کنند. می‌توانید از آیتم‌های منو برای باز کردن نوارهای کناری و دیالوگ‌ها استفاده کنید زیرا در AuthMode.FULL اجرا می‌شوند .

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

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

عیب‌یابی رندر نشدن منوهای افزودنی

اگر کد شما حالت‌های مجوز را به درستی مدیریت نکند، ممکن است منوی افزودنی شما نمایش داده نشود. مثلا:

• یک افزونه سعی می کند یک سرویس Apps Script را اجرا کند که توسط حالت مجوز فعلی پشتیبانی نمی شود.

• یک افزونه سعی می کند یک تماس سرویس را قبل از تعامل کاربر با آن اجرا کند.

برای حذف یا تنظیم مجدد یک تماس سرویس که باعث ایجاد خطاهای مجوز در AuthMode.NONE می شود، اقدامات زیر را امتحان کنید:

1. پروژه Apps Script را برای افزونه خود باز کنید و تابع onOpen() را پیدا کنید.
2. تابع onOpen() برای ذکر خدمات Apps Script یا اشیاء مرتبط با آنها، مانند PropertiesService ، SpreadsheetApp یا GmailApp جستجو کنید.
3. اگر سرویسی برای چیزی غیر از ایجاد عناصر رابط کاربری استفاده می شود، آن را حذف کنید یا در یک بلوک نظر قرار دهید. فقط این متدها را بگذارید: .getUi() .createMenu() ، .addItem() و .addToUi() . همچنین هر سرویسی را که خارج از یک تابع است پیدا و حذف کنید.
4. توابعی را که می توانند حاوی خطوط کدی هستند که در مرحله قبل توضیح داده شده یا حذف شده اند، شناسایی کنید، به ویژه آنهایی که از اطلاعاتی که تولید می کنند استفاده می کنند، و فراخوانی های سرویس را به توابعی که به آنها نیاز دارند منتقل کنید. برای تطبیق با تغییرات ایجاد شده در مراحل قبلی، پایگاه کد خود را مجدداً مرتب یا بازنویسی کنید.

5. کد را ذخیره کنید و یک استقرار آزمایشی ایجاد کنید.

   هنگامی که یک پیاده‌سازی آزمایشی ایجاد می‌کنید، مطمئن شوید که فیلد Config برای کاربر فعلی نصب شده است و متن زیر کادر Config می‌گوید Test in AuthMode.None

6. استقرار آزمایشی را اجرا کنید و منوی Extensions را باز کنید.

7. اگر همه آیتم های منو نمایش داده شوند، مشکل برطرف شده است. اگر فقط منوی راهنما را می بینید، به مرحله 1 برگردید. ممکن است تماس سرویس را از دست داده باشید.

مطالب مرتبط

• برنامه های وب
• انواع افزونه ها
• یک افزونه ویرایشگر را آزمایش کنید