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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تنطبق أوضاع التفويض على جميع طرق تنفيذ 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();
}

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

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

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

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

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

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

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

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