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

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

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

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

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

عرض النطاقات

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

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

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

تعيين نطاقات صريحة

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

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

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

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

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

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

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

5. احفظ التغييرات التي تم إجراؤها على ملف البيان.

التحقّق من بروتوكول OAuth

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

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

نطاقات مشروطة

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

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

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

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

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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