تفويض إضافة المحرِّر

يكون تفويض العديد من التطبيقات المستندة إلى "برمجة تطبيقات Google" أمرًا مباشرًا لأن مشروع النصوص البرمجية يطلب أي أذونات مفقودة يحتاج إليها عندما يحاول شخص استخدامها.

ويكون نموذج التفويض لإضافات المحرّر أكثر تعقيدًا لعدة أسباب:

• عندما ينشئ المستخدم ملفًا، يتم إدراج جميع الإضافات التي يثبّتها المستخدم في قائمة الإضافات، حتى إذا لم يصادق المستخدم على هذه الإضافات بعد.

• تعمل هذه الإضافات على الملفات في Google Drive التي يمكن مشاركتها مع المتعاونين. والمتعاونون الذين لم يتم تثبيت إضافة المحرر الإضافية لهم يرونها في المستندات التي استخدمها منشئ الملف.

• تعمل إضافات المحرّر تلقائيًا على تشغيل دوال onOpen() عند فتح مستند.

لحماية بيانات المستخدمين، يتم تطبيق أوضاع التفويض التي تجعل بعض الخدمات غير متاحة لخدمة "onOpen()". يمكن أن يساعدك هذا الدليل في فهم ما يمكن أن تفعله التعليمات البرمجية ومتى.

نموذج التفويض

يعتمد وضع التفويض لإضافة ميزات "محرّر إعلانات Google" على حالتها، استنادًا إلى من يستخدمها: المستخدم الذي ثبَّت الإضافة أو المتعاون.

حالات إضافة المحرّر

يتم تثبيت إضافات المحرّر في القائمة الإضافات أو تفعيلها أو كلاهما.

• يتم تثبيت إضافة لمستخدم معيّن بعد أن يحصل عليها هذا المستخدم أو مشرفه من Google Workspace Marketplace ويمنحها الإذن بالوصول إلى بياناته على Google.
• يتم تفعيل الإضافة في مستند أو نموذج أو عرض تقديمي أو جدول بيانات عندما يستخدمها أي شخص هناك.
• عندما يتعاون الأشخاص في ملف ويستخدم أحدهم إضافة، يتم تثبيتها لمستخدم واحد، وتفعيلها للملف.

يلخص الجدول التالي الفروق بين العناصر المثبتة والمفعَّلة. تجدر الإشارة إلى أنّه عند اختبار نص برمجي كإضافة، يمكنك إجراء الاختبار بإحدى هاتين الحالتين أو كلتاهما.

	تم التثبيت	مُفعَّل
ينطبق على	المستخدِم	مستند أو نموذج أو عرض تقديمي أو جدول بيانات
بسبب	الحصول على إضافة من المتجر	الحصول على إضافة من المتجر أثناء استخدام ذلك المستند أو النموذج أو العرض التقديمي أو جدول البيانات، أو استخدام إضافة سبق تثبيتها في ذلك المستند أو النموذج أو العرض التقديمي أو جدول البيانات
القائمة مرئية لـ	ذلك المستخدم فقط، في جميع المستندات أو النماذج أو العروض التقديمية أو جداول البيانات التي يفتحها أو ينشئها	جميع المتعاونين في ذلك المستند أو النموذج أو العرض التقديمي أو جدول البيانات
وضع التفويض لـ onOpen()	AuthMode.NONE (ما لم يكن مفعَّلاً أيضًا، في هذه الحالة AuthMode.LIMITED)	AuthMode.LIMITED

أوضاع التفويض

يتم تشغيل الوظيفة onOpen() لإضافة المحرر تلقائيًا عندما يفتح المستخدم مستندًا أو نموذجًا أو عرضًا تقديميًا أو جدول بيانات. لحماية بيانات المستخدمين، تفرض "برمجة التطبيقات" قيودًا على المهام التي يمكن أن تؤديها دالة onOpen(). وتحدّد حالة إضافة المحرِّر وضع التفويض الذي يتم فيه تشغيل وظيفة onOpen().

إذا كانت إحدى إضافات المحرِّر مفعّلة في الملف أو النموذج أو العرض التقديمي أو جدول البيانات، سيتم تنفيذ onOpen() في AuthMode.LIMITED. إذا كانت الإضافة غير مفعّلة وتم تثبيتها فقط، سيتم تشغيل "onOpen()" في AuthMode.NONE.

في AuthMode.NONE، لا يمكن لأي إضافة تشغيل خدمات معيّنة إلى أن يتفاعل المستخدم مع الإضافة من خلال النقر على وظائف مخصَّصة أو تشغيلها. إذا حاولت الإضافة استخدام هذه الخدمات في onOpen() أو onInstall() أو في نطاق عام، تتعذّر الأذونات واستدعاءات أخرى، مثل ملء القوائم أو إيقاف. المساعدة هي الخيار الوحيد المتاح.

لتشغيل طلبات الخدمات المحظورة، يجب استخدام وضع التفويض AuthMode.FULL. لا يتم تشغيل دوال تفاعل المستخدم، مثل النقر فوق أحد خيارات القائمة، إلا في هذا الوضع فقط. بعد تشغيل الرمز في وضع AuthMode.FULL، يمكن للإضافة استخدام جميع النطاقات التي سمح بها المستخدم.

تفعِّل "برمجة التطبيقات" وضع التفويض باعتبارها السمة authMode في مَعلمة الحدث لبرمجة التطبيقات، وهي e، حيث تتوافق قيمة e.authMode مع قيمة ثابتة في تعداد "برمجة تطبيقات Google" ScriptApp.AuthMode.

تنطبق أوضاع التفويض على جميع طرق تنفيذ "برمجة التطبيقات"، بما في ذلك التنفيذ من مُحرِّر النصوص البرمجية، أو من عنصر في القائمة، أو من استدعاء برمجة تطبيقات google.script.run. ومع ذلك، لا يمكن فحص السمة e.authMode إلا إذا تم تشغيل النص البرمجي كنتيجة لمشغّل مثل onOpen() أو onEdit() أو onInstall(). تستخدم الدوال المخصصة في "جداول بيانات Google" وضع التفويض الخاص بها، AuthMode.CUSTOM_FUNCTION، الذي يشبه LIMITED ولكن لها قيود مختلفة قليلاً. بالنسبة إلى جميع الحالات الأخرى، يتم تشغيل النصوص البرمجية في AuthMode.FULL، كما هو موضح في الجدول التالي.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
يحدث لـ	onOpen() (إذا ثبّت المستخدم إضافة بدون تفعيلها في المستند أو النموذج أو العرض التقديمي أو جدول البيانات)	onOpen() (جميع الأوقات الأخرى) onEdit() (في "جداول بيانات Google" فقط)	الدوال المخصّصة	جميع الأوقات الأخرى، بما في ذلك: مشغّلات قابلة للتثبيت onInstall() google.script.run
الوصول إلى بيانات المستخدمين	اللغة فقط	اللغة فقط	اللغة فقط	نعم
الوصول إلى مستند أو نموذج أو عرض تقديمي أو جدول بيانات	لا	نعم	نعم — للقراءة فقط	نعم
الوصول إلى واجهة المستخدم	إضافة أصناف إلى القائمة	إضافة أصناف إلى القائمة	لا	نعم
إذن الوصول إلى "Properties"	لا	نعم	نعم	نعم
إذن الوصول إلى "Jdbc" و"UrlFetch"	لا	لا	نعم	نعم
خدمات أخرى	Logger Utilities	أي خدمات لا يمكنها الوصول إلى بيانات المستخدمين	أي خدمات لا يمكنها الوصول إلى بيانات المستخدمين	جميع الخدمات

مراحل نشاط التفويض لإضافة ميزات "محرّر إعلانات Google"

عند تثبيت إحدى الإضافات للمستخدم الحالي أو تفعيلها في الملف الحالي، يتم تحميل الإضافة للمستند أو النموذج أو العرض التقديمي أو جدول البيانات عند فتح هذا الملف. يتم إدراج الإضافة في قائمة الإضافات وتبدأ في الاستماع إلى العوامل البسيطة 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();
}

يُرجى العِلم أنّه لا يمكن للإضافات فتح الأشرطة الجانبية أو مربّعات الحوار أثناء التنفيذ في AuthMode.LIMITED. يمكنك استخدام عناصر القائمة لفتح الأشرطة الجانبية ومربعات الحوار منذ تشغيلها في AuthMode.FULL.

تشغيل المستخدِم "إضافة المحرِّر"

عندما ينقر المستخدم على عنصر قائمة الإضافات، تتحقّق "برمجة التطبيقات" أولاً مما إذا كان المستخدم قد ثبَّت الإضافة وتطلب منه إجراء ذلك إذا لم يثبّتها. إذا سمح المستخدم بالإضافة، يشغِّل النص البرمجي الدالة المقابلة لعنصر القائمة في AuthMode.FULL. يتم تمكين الوظيفة الإضافية في المستند أو النموذج أو العرض التقديمي أو جدول البيانات إذا لم يتم تفعيلها بالفعل.

تحديد وحلّ المشاكل المتعلّقة بعدم عرض قوائم الإضافات

قد لا يتم عرض قائمة الإضافات إذا لم تكن التعليمات البرمجية تدير أوضاع التفويض بشكل صحيح. مثلاً:

• تحاول الإضافة تشغيل خدمة "برمجة تطبيقات Google" التي لا تتوافق مع وضع التفويض الحالي.

• تحاول الإضافة تشغيل طلب الخدمة قبل أن يتفاعل المستخدم معها.

لإزالة طلب خدمة أو إعادة ترتيبه ويتسبب في حدوث أخطاء في الأذونات في AuthMode.NONE، جرِّب الإجراءات التالية:

1. افتح مشروع "برمجة تطبيقات Google" للإضافتك وحدِّد موقع دالة onOpen().
2. ابحث في الدالة onOpen() عن الإشارات إلى خدمات "برمجة التطبيقات" أو العناصر المرتبطة بها، مثل PropertiesService أو SpreadsheetApp أو GmailApp.
3. إذا تم استخدام الخدمة لأي شيء بخلاف إنشاء عناصر واجهة المستخدم، فعليك إزالتها أو وضعها في كتلة تعليقات. يجب ترك هذه الطرق فقط: .getUi() و.createMenu() و.addItem() و.addToUi(). كما يمكنك البحث عن أي خدمة خارج الدالة وإزالتها.
4. حدد الدوال التي يمكن أن تحتوي على سطور من التعليمات البرمجية تم التعليق عليها أو إزالتها في الخطوة السابقة، لا سيما تلك التي تستخدم المعلومات التي تنتجها، وانقل استدعاءات الخدمة إلى الدوال التي تحتاج إليها. أعد ترتيب قاعدة التعليمات البرمجية أو أعد كتابتها لتلائم التغييرات التي تم إجراؤها في الخطوات السابقة.

5. احفظ الرمز وأنشِئ عملية نشر تجريبية.

   عند إنشاء عملية نشر تجريبية، تأكّد من أنّ الحقل الضبط هو مثبّت للمستخدم الحالي وأنّ النص أسفل مربّع "الإعداد" ينص على الاختبار في AuthMode.None

6. ابدأ النشر التجريبي وافتح قائمة الإضافات.

7. في حال عرض جميع عناصر القائمة، تم حلّ المشكلة. إذا لم تظهر لك سوى القائمة مساعدة، ارجع إلى الخطوة 1. ربما فاتتك مكالمة خدمة.

مواضيع ذات صلة

• تطبيقات الويب
• أنواع الإضافات
• اختبار إضافة "محرِّر"