مصادقة إضافة المحرِّر

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

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

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

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

• تعمل إضافات "محرّر Google" تلقائيًا على تنفيذ onOpen() وظائفها عند فتح مستند.

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

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

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

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

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

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

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

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

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

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

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

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

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

تنطبق أوضاع التفويض على جميع طرق تنفيذ Apps Script، بما في ذلك التشغيل من محرِّر النصوص البرمجية أو من عنصر قائمة أو من استدعاء Apps Script google.script.run. ومع ذلك، لا يمكن فحص السمة e.authMode إلا إذا تم تشغيل النص البرمجي نتيجةً لعامل تشغيل مثل onOpen() أو onEdit() أو onInstall(). تستخدِم الدوال المخصّصة في "جداول بيانات Google" وضع التفويض الخاص بها، وهو 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();
}

لإضافة عناصر قائمة ديناميكية استنادًا إلى خصائص 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();
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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