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

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

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

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

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

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

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

مدل مجوزدهی

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

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

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

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

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

حالت‌های مجوزدهی

تابع 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 فقط در صورتی قابل بررسی است که اسکریپت در نتیجه یک trigger مانند onOpen ، onEdit یا onInstall اجرا شود. توابع سفارشی در Google Sheets از حالت مجوزدهی خاص خود، AuthMode.CUSTOM_FUNCTION ، استفاده می‌کنند که مشابه LIMITED است اما محدودیت‌های کمی متفاوت دارد. برای سایر موارد، اسکریپت‌ها در AuthMode.FULL اجرا می‌شوند، همانطور که در جدول زیر توضیح داده شده است.

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

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

مباحث مرتبط

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