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

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

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

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

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

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

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

مدل مجوزدهی

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

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

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

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

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

	نصب شده	فعال شده
اعمال می‌شود به	کاربر	سند، فرم، ارائه یا صفحه گسترده
ناشی از	دریافت افزونه از فروشگاه	دریافت افزونه از فروشگاه هنگام استفاده از آن سند، فرم، ارائه یا صفحه گسترده، یا استفاده از افزونه‌ای که قبلاً نصب شده است در آن سند، فرم، ارائه یا صفحه‌گسترده
منوی قابل مشاهده برای	فقط آن کاربر، در تمام اسناد، فرم‌ها، ارائه‌ها یا صفحات گسترده‌ای که باز یا ایجاد می‌کند	همه همکاران در آن سند، فرم، ارائه یا صفحه گسترده
حالت مجوز برای 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 است.

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

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

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

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

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

وقتی یک افزونه‌ی ویرایشگر از فروشگاه نصب می‌شود، تابع 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();
}

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

نمونه زیر یک تابع پیشرفته 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 اجرا می‌شوند .

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

وقتی کاربر روی یک آیتم منوی افزونه‌ها کلیک می‌کند، 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. کد را ذخیره کنید و یک استقرار آزمایشی ایجاد کنید.

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

6. مرحله‌ی آزمایشی نصب را اجرا کنید و منوی افزونه‌ها (Extensions) را باز کنید.

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

مباحث مرتبط

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