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

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

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

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

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

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

نطاقات العرض

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

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

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

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

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

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

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

يمكنك ضبط النطاقات التي يستخدمها مشروع النص البرمجي بشكل صريح من خلال تعديل ملف بيان المشروع. حقل البيان 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 في "برمجة التطبيقات"
• التطبيقات التي لم يتم التحقّق منها
• الأسئلة الشائعة حول التحقّق من OAuth
• خدمة Google APIs: سياسة بيانات المستخدمين

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

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

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

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

تقدّم إضافة "أدوات المطوّرين في Google Workspace" لبرنامج Visual Studio Code معلومات تشخيصية لجميع النطاقات، بما في ذلك وصف النطاق وما إذا كان حسّاسًا أو محظورًا.

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

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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

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