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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تنطبق أوضاع التفويض على جميع طرق تنفيذ برمجة تطبيقات، بما في ذلك التنفيذ من أداة تعديل النصوص البرمجية أو من صنف في القائمة أو من استدعاء 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();
}

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

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

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

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

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

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

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

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

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

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

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

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