نطاقات التفويض لإضافات المحرّر

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

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

يمكنك تحديد النطاقات في manifest باستخدام سلاسل عناوين URL. أثناء مسار التفويض، تعرِض Apps Script وصفًا يسهل على المستخدم فهمه للنطاق. على سبيل المثال، قد تستخدم الإضافة نطاق "قراءة المستند الحالي"، والذي يتم كتابته في البيان على النحو التالي:https://www.googleapis.com/auth/documents.currentonly. أثناء عملية التفويض، تطلب الإضافة التي تملك هذا النطاق من المستخدم السماح للإضافة بـ: عرض المستندات التي تم تثبيت هذا التطبيق فيها وإدارتها.

ملاحظة: لا يتوفّر نطاق currentonly إلا ضمن خدمات Apps Script. ولا يشمل ذلك الخدمات المتقدّمة في Apps Script أو طلبات البيانات المباشرة إلى واجهات برمجة تطبيقات Google Workspace.

ملاحظة: تتداخل النطاقات التي تستخدمها Apps Script لخدماتها المختلفة مع النطاقات التي تستخدمها واجهة برمجة التطبيقات ذات الصلة. على سبيل المثال، تستخدم خدمة "تقويم Google" في Apps Script العديد من النطاقات نفسها التي تستخدمها Calendar API. يمكنك البحث عن النطاقات التي تتطلّب طرق خدمة معيّنة في Apps Script في مستندات مرجعية Apps Script.

نطاقات العرض

يمكنك الاطّلاع على النطاقات التي يتطلبها مشروع النصوص البرمجية حاليًا من خلال تنفيذ الخطوات التالية:

1. افتح مشروع النص.
2. على يمين الصفحة، انقر على نظرة عامة .
3. اطّلِع على النطاقات ضمن "نطاقات OAuth للمشروع".

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

ضبط نطاقات صريحة

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

على سبيل المثال، قد تمنح "برمجة تطبيقات Google" مشروع نص برمجي إضافيًا https://mail.google.com النطاق المسموح به للغاية بشكلٍ تلقائي. عندما يفوّض مستخدم أحد مشاريع النصوص البرمجية بهذا النطاق، يحصل المشروع على إذن وصول كامل إلى حساب Gmail الخاص بالمستخدم. بالنسبة إلى الإضافات المنشورة، يجب استبدال هذا النطاق بمجموعة محدودة تلبي احتياجات الإضافات فقط.

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

يمكنك تحديد النطاقات التي يستخدمها مشروع النصوص البرمجية صراحةً من خلال تعديلملف manifest المشروع. حقل البيان oauthScopes هو صفيف لجميع النطاقات التي تستخدمها الإضافة. لضبط نطاقات مشروعك، اتّبِع الخطوات التالية:

1. الاطّلاع على النطاقات التي تستخدمها الإضافة حاليًا حدِّد التغيُّرات التي يجب إجراؤها، مثل استخدام نطاق أضيَق.
2. افتح ملف بيان الملحق.
3. ابحث عن الحقل ذي المستوى الأعلى الذي يحمل التصنيف oauthScopes. إذا لم يكن متوفّرًا، يمكنك إضافته.

4. يحدّد الحقل oauthScopes صفيفًا من السلاسل. لضبط النطاقات التي يستخدمها مشروعك، استبدِل محتوى هذا الصفيف بالنطاقات التي تريده استخدامها. على سبيل المثال، بالنسبة إلى إضافة "محرر" تُوسّع نطاق "جداول بيانات Google"، قد يكون لديك ما يلي:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/script.container.ui",
       "https://www.googleapis.com/auth/spreadsheets"
     ],
     ...
   }
   

5. احفظ التغييرات في ملف البيان.

إثبات ملكية حساب OAuth

قد يتطلّب استخدام نطاقات OAuth حسّاسة معيّنة أن تخضع الإضافة لمحاولة إثبات ملكية عميل OAuth قبل أن تتمكّن من نشرها. لمزيد من المعلومات، يُرجى الاطّلاع على الأدلة التالية:

• التحقّق من عميل OAuth في Apps Script
• التطبيقات التي لم يتم التحقّق منها
• الأسئلة الشائعة حول عملية التحقّق من OAuth
• خدمة Google APIs: سياسة بيانات المستخدمين

النطاقات المحظورة

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

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

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

نطاقات إضافات المحرّر

عند إنشاء إضافة "محرِّر"، يتم تحديد النطاقات المطلوبة من خلال خدمة "برمجة تطبيقات Google" والطُرق التي تستخدمها رموز الإضافات. على سبيل المثال، قد تحتاج إحدى الإضافات في "جداول بيانات Google" إلى النطاق https://www.googleapis.com/auth/spreadsheets.readonly لقراءة المعلومات من "جداول بيانات Google" المختلفة.

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

إذا لم تكن تضبط نطاقاتك بشكل صريح وكانت "إضافة المحرِّر" تقرأ أو تكتب في ملف المحرِّر المفتوح فقط، أضِف التعليق التالي إلى أحد ملفات مشروع النصوص البرمجية:

  /**
   * @OnlyCurrentDoc
   */

يطلب هذا التعليق من Apps Script تضييق نطاق ملف المحرِّر الذي يضبطه على currentonly. على سبيل المثال، في حال إضافة هذا التعليق إلى ملف مشروع ملف نصي لإضافة "جداول بيانات Google"، يعني ذلك أنّ الإضافة لا تحتاج إلا إلى إذن للعمل على جدول البيانات المفتوح حاليًا، وليس أي جداول بيانات أخرى قد يمتلكها المستخدم في Google Drive. في المقابل، يجب عدم استخدام هذا التعليق إذا كانت إضافة "جداول بيانات Google" تحتاج إلى قراءة البيانات أو كتابتها في "جدول بيانات" لم يفتحه المستخدم حاليًا.

ملاحظة: لا يتوفّر نطاق currentonly إلا ضمن خدمات Apps Script. ولا يشمل ذلك الخدمات المتقدّمة في Apps Script أو طلبات البيانات المباشرة إلى واجهات برمجة تطبيقات Google Workspace.