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

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

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

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

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

عرض النطاقات

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

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

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

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

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

على سبيل المثال، قد تمنح "برمجة التطبيقات" مشروع نص برمجي لإضافة النطاق المتساهل جدًا 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 قبل أن تتمكّن من نشره. لمزيد من المعلومات، يُرجى الاطّلاع على الأدلة التالية:

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

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

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

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

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

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

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

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

/**
 * @OnlyCurrentDoc
 */

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