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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تنطبق أوضاع التفويض على جميع طرق تنفيذ Apps Script، بما في ذلك التنفيذ من محرّر النصوص البرمجية أو من عنصر قائمة أو من استدعاء google.script.run في Apps Script. ومع ذلك، لا يمكن فحص السمة 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	أي خدمات لا تصل إلى بيانات المستخدم	أي خدمات لا تصل إلى بيانات المستخدم	جميع الخدمات

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

عند تثبيت إضافة للمستخدم الحالي أو تفعيلها في الملف الحالي، يتم تحميل الإضافة للمستند أو النموذج أو العرض التقديمي أو جدول البيانات عند فتح هذا الملف. تظهر الإضافة في قائمة الإضافات وتبدأ في الاستماع إلى أوامر التشغيل البسيطة 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(). إذا تعذّر على الإضافة المنشورة إضافة عناصر القائمة، راجِع وحدة تحكّم JavaScript في المتصفّح لمعرفة ما إذا تم عرض خطأ. بعد ذلك، راجِع النص البرمجي لمعرفة ما إذا كانت الدالة onOpen() أو المتغيرات العامة تستدعي خدمات غير مسموح بها في AuthMode.NONE.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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