المناظير

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

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

يمكنك تحديد النطاقات في ملف البيان باستخدام سلاسل عناوين URL. أثناء عملية التفويض، يعرض Apps Script للمستخدم وصفًا للنطاق يمكن قراءته. على سبيل المثال، قد تستخدم إضافة Google Workspace النطاق "قراءة الرسالة الحالية"، والذي تتم كتابته في ملف البيان على النحو التالي: https://www.googleapis.com/auth/gmail.addons.current.message.readonly. أثناء عملية منح الإذن، تطلب إضافة تتضمّن هذا النطاق من المستخدم السماح لها بما يلي: عرض رسائل البريد الإلكتروني عندما تكون الإضافة مشغّلة.

ملاحظة: تتداخل النطاقات التي تستخدمها "خدمة 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 Workspace التي توسّع نطاق Gmail، قد يتوفّر لك ما يلي:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

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

التحقّق من OAuth

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

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

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

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

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

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

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

اختيار نطاقات إضافات Google Workspace

توفّر الأقسام التالية النطاقات الشائعة الاستخدام لإضافات Google Workspace.

نطاقات المحرّر

في ما يلي النطاقات الأكثر استخدامًا لإضافات Google Workspace التي توسّع وظائف "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google".

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

النطاق
الوصول إلى ملفات "مستندات Google" الحالية	https://www.googleapis.com/auth/documents.currentonly مطلوب إذا كانت الإضافة تصل إلى واجهة برمجة التطبيقات Docs API في "برمجة التطبيقات". يمنح إذن الوصول المؤقت إلى محتوى المستند المفتوح.
الوصول إلى ملف "جداول بيانات Google" الحالي	https://www.googleapis.com/auth/spreadsheets.currentonly مطلوب إذا كانت الإضافة تصل إلى Sheets API في "برمجة تطبيقات Google". يمنح إذن الوصول المؤقت إلى محتوى جدول البيانات المفتوح.
الوصول إلى ملف "الشرائح الحالية"	https://www.googleapis.com/auth/presentations.currentonly مطلوب إذا كانت الإضافة تصل إلى Slides API في "برمجة التطبيقات". يمنح هذا الإذن إمكانية الوصول المؤقت إلى محتوى العرض التقديمي المفتوح.
الوصول إلى كل ملف على حدة	https://www.googleapis.com/auth/drive.file مطلوب للسماح للإضافة باستخدام onFileScopeGrantedTrigger وفي حال وصول الإضافة إلى واجهة برمجة التطبيقات في "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو Drive يمنح هذا النطاق إذن الوصول إلى الملفات التي ينشئها التطبيق أو يفتحها، وذلك باستخدام خدمة Drive المتقدّمة في Apps Script. ولا يسمح هذا الإذن باستخدام إجراءات مشابهة باستخدام خدمة Drive الأساسية. يتم منح إذن الوصول إلى الملفات على أساس كل ملف على حدة، ويتم إبطاله عندما يلغي المستخدم الإذن للتطبيق.

Gmail

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

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

احرص أيضًا على استبدال النطاق الواسع جدًا https://mail.google.com في الإضافة بمجموعة أضيق من النطاقات التي تسمح بالتفاعلات التي تحتاجها الإضافة فقط.

النطاق
صياغة مسودّات جديدة	https://www.googleapis.com/auth/gmail.addons.current.action.compose مطلوب إذا كان التطبيق الإضافي يستخدم مشغّلات إجراءات الإنشاء. يسمح للإضافة بإنشاء مسودات جديدة للرسائل والردود بشكل مؤقت. راجِع مقالة إنشاء رسائل مسودّة للحصول على التفاصيل. غالبًا ما يتم استخدام هذا النطاق أيضًا مع إجراءات الإنشاء. يتطلّب ذلك رمز دخول.
قراءة البيانات الوصفية للرسائل المفتوحة	https://www.googleapis.com/auth/gmail.addons.current.message.metadata يمنح هذا النطاق إذن الوصول المؤقت إلى البيانات الوصفية للرسالة المفتوحة (مثل الموضوع أو المستلمين). لا تسمح بقراءة محتوى الرسالة وتتطلّب رمز دخول. مطلوب إذا كان التطبيق الإضافي يستخدم البيانات الوصفية في مشغّلات إجراء الإنشاء. بالنسبة إلى إجراءات الإنشاء، يكون هذا النطاق مطلوبًا إذا كان مشغّل الإنشاء بحاجة إلى الوصول إلى البيانات الوصفية. في الواقع، يتيح هذا النطاق لمشغّل الإنشاء الوصول إلى قوائم المستلمين (إلى ونسخة إلى ونسخة مخفية الوجهة) لمسودة رسالة إلكترونية للرد.
قراءة محتوى الرسالة المفتوحة	https://www.googleapis.com/auth/gmail.addons.current.message.action يمنح هذا النطاق إذن الوصول إلى محتوى الرسالة المفتوحة عند تفاعل المستخدم معها، مثلما يحدث عند اختيار عنصر من قائمة الإضافة. يتطلّب ذلك رمز دخول.
قراءة محتوى سلسلة المحادثات المفتوحة	https://www.googleapis.com/auth/gmail.addons.current.message.readonly يمنح إذن وصول مؤقتًا إلى البيانات الوصفية للملف المفتوح ومحتواه. يمنح هذا الإذن أيضًا إمكانية الوصول إلى محتوى الرسائل الأخرى في سلسلة المحادثات المفتوحة. يتطلّب ذلك رمز دخول.
قراءة أي محتوى رسالة وبياناتها الوصفية	https://www.googleapis.com/auth/gmail.readonly قراءة أي بيانات وصفية ومحتوى للرسائل الإلكترونية، بما في ذلك الرسالة المفتوحة مطلوب إذا كنت بحاجة إلى قراءة معلومات عن رسائل أخرى، مثل عند إجراء طلب بحث أو قراءة سلسلة محادثات بريدية كاملة. تحذير: هذا نطاق واسع جدًا ومقيّد. لا تستخدِمها إلا عند الضرورة القصوى.

نطاقات "تقويم Google"

في ما يلي النطاقات الشائعة الاستخدام لإضافات Google Workspace التي توسّع نطاق "تقويم Google".

النطاق
الوصول إلى البيانات الوصفية للأحداث	https://www.googleapis.com/auth/calendar.addons.execute مطلوب إذا كانت الإضافة تصل إلى البيانات الوصفية لأحداث "تقويم Google". يسمح هذا الإذن للإضافة بالوصول إلى البيانات الوصفية للأحداث.
قراءة بيانات الأحداث التي ينشئها المستخدم	https://www.googleapis.com/auth/calendar.addons.current.event.read مطلوب إذا كانت الإضافة بحاجة إلى قراءة بيانات الأحداث التي ينشئها المستخدم. يسمح هذا الإذن للإضافة بالوصول إلى بيانات الأحداث التي ينشئها المستخدم. لا تتوفّر هذه البيانات إلا إذا تم ضبط حقل البيان addOns.calendar.eventAccess على READ أو READ_WRITE.
كتابة بيانات الأحداث التي ينشئها المستخدم	https://www.googleapis.com/auth/calendar.addons.current.event.write مطلوب إذا كانت الإضافة بحاجة إلى كتابة بيانات الأحداث التي ينشئها المستخدم. يسمح هذا الإذن للإضافة بتعديل بيانات الأحداث التي ينشئها المستخدم. لا تتوفّر هذه البيانات إلا إذا تم ضبط حقل البيان addOns.calendar.eventAccess على WRITE أو READ_WRITE.

نطاقات Google Chat

لاستدعاء Chat API، يجب المصادقة بصفتك مستخدم Google Chat أو تطبيق Chat. يتطلّب كل نوع من أنواع المصادقة نطاقات مختلفة، ولا تتيح جميع طرق Chat API مصادقة التطبيق.

لمزيد من المعلومات عن نطاقات Chat وأنواع المصادقة، يُرجى الاطّلاع على نظرة عامة حول المصادقة والتفويض في Chat API.

يعرض الجدول التالي طرق Chat API ونطاقاتها الشائعة الاستخدام استنادًا إلى أنواع المصادقة المتوافقة:

الطريقة	مصادقة المستخدم متاحة	مصادقة التطبيقات متاحة	نطاقات التفويض المتاحة
إرسال رسالة			باستخدام مصادقة المستخدم: chat.messages.create chat.messages chat.import باستخدام مصادقة التطبيق: chat.bot
إنشاء مساحة			باستخدام مصادقة المستخدم: chat.spaces.create chat.spaces chat.import باستخدام مصادقة التطبيق وموافقة المشرف (متاحتان في إصدار Developer Preview): chat.app.spaces.create chat.app.spaces
إنشاء مساحة وإضافة أعضاء إليها		—	باستخدام مصادقة المستخدم: chat.spaces.create chat.spaces
إضافة مستخدم إلى مساحة			باستخدام مصادقة المستخدم: chat.memberships chat.memberships.app chat.import باستخدام مصادقة التطبيق وموافقة المشرف (متاحتان في إصدار Developer Preview): chat.app.memberships
عرض الأنشطة أو الأحداث من مساحة في Chat		—	في حال استخدام مصادقة المستخدم، يجب استخدام نطاق لكل نوع حدث مضمّن في الطلب: بالنسبة إلى الأحداث المتعلّقة بالرسائل: chat.messages chat.messages.readonly بالنسبة إلى الأحداث المتعلقة بالتفاعلات: chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly بالنسبة إلى الأحداث المتعلقة بالعضويات: chat.memberships chat.memberships.readonly بالنسبة إلى الأحداث المتعلقة بالمساحة: chat.spaces chat.spaces.readonly

نطاقات Google Drive

في ما يلي النطاقات المستخدَمة بشكل متكرر لإضافات Google Workspace التي توسّع نطاق Google Drive.

النطاق
قراءة البيانات الوصفية للعنصر المحدّد	https://www.googleapis.com/auth/drive.addons.metadata.readonly مطلوب إذا كانت الإضافة تنفّذ واجهة سياقية يتم تشغيلها عندما يختار المستخدم عناصر في Drive. تسمح هذه الإضافة بقراءة بيانات وصفية محدودة حول العناصر التي اختارها المستخدم في Google Drive. تقتصر البيانات الوصفية على رقم تعريف العنصر وعنوانه ونوع MIME وعنوان URL للرمز وما إذا كان لدى الإضافة إذن بالوصول إلى العنصر.
الوصول إلى كل ملف على حدة	https://www.googleapis.com/auth/drive.file ننصحك باستخدام هذا الخيار إذا كانت الإضافة بحاجة إلى الوصول إلى ملفات فردية في Drive. يمنح هذا النطاق إذن الوصول إلى الملفات التي ينشئها التطبيق أو يفتحها، وذلك باستخدام خدمة Drive المتقدّمة في Apps Script. ولا يسمح هذا الإذن باستخدام إجراءات مشابهة باستخدام خدمة Drive الأساسية. يتم منح إذن الوصول إلى الملفات على أساس كل ملف على حدة، ويتم إبطاله عندما يلغي المستخدم تفويض التطبيق. راجِع مثال طلب الوصول إلى الملفات المحدّدة.

رموز الدخول

لحماية بيانات المستخدمين، لا تمنح نطاقات Gmail المستخدَمة في إضافات Google Workspace سوى إذن وصول مؤقت إلى بيانات المستخدمين. لتفعيل إذن الوصول المؤقت، يجب استدعاء الدالة GmailApp.setCurrentMessageAccessToken(accessToken) باستخدام رمز دخول كمعلَمة. يجب الحصول على رمز دخول من عنصر حدث إجراء.

ملاحظة: رمز الدخول الذي يتيح نطاقات Gmail ليس هو نفسه رمز الدخول الذي تعرضه الدالة ScriptApp.getOAuthToken(). يجب استخدام الرمز المميّز المقدَّم في عنصر حدث الإجراء.

يوضّح المثال التالي كيفية ضبط رمز مميز للدخول للسماح بالوصول إلى البيانات الوصفية الخاصة بإحدى الرسائل. النطاق الوحيد اللازم لهذا المثال هو https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

نطاقات Google Workspace الأخرى

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

يعرض الجدول التالي قائمة بالنطاقات التي تستخدمها إضافات Google Workspace غالبًا:

النطاق
قراءة عنوان البريد الإلكتروني للمستخدم	https://www.googleapis.com/auth/userinfo.email يتيح هذا الإذن للمشروع قراءة عنوان البريد الإلكتروني للمستخدم الحالي.
السماح بإجراء مكالمات إلى خدمات خارجية	https://www.googleapis.com/auth/script.external_request يسمح هذا الإذن للمشروع بإرسال طلبات UrlFetch. يجب أيضًا تنفيذ هذا الإجراء إذا كان المشروع يستخدم مكتبة OAuth2 لبرمجة التطبيقات.
قراءة اللغة والمنطقة الزمنية للمستخدم	https://www.googleapis.com/auth/script.locale يسمح للمشروع بمعرفة اللغة والمنطقة الزمنية للمستخدم الحالي. لمزيد من التفاصيل، يُرجى الاطّلاع على الوصول إلى اللغة والمنطقة الزمنية للمستخدم.
إنشاء مشغّلات	https://www.googleapis.com/auth/script.scriptapp يسمح للمشروع بإنشاء مشغِّلات.
معاينة الروابط التابعة لجهات خارجية	https://www.googleapis.com/auth/workspace.linkpreview مطلوب إذا كانت الإضافة تعرِض معاينات للروابط من خدمة تابعة لجهة خارجية. يسمح للمشروع بالاطّلاع على رابط في أحد تطبيقات Google Workspace أثناء تفاعل المستخدم معه. لمزيد من المعلومات، اطّلِع على معاينة الروابط باستخدام الشرائح الذكية.
إنشاء موارد تابعة لجهات خارجية	https://www.googleapis.com/auth/workspace.linkcreate مطلوبة إذا كانت الإضافة تنشئ موارد في خدمة تابعة لجهة خارجية. يسمح هذا النطاق للمشروع بقراءة المعلومات التي يرسلها المستخدمون إلى نموذج إنشاء المراجع وإدراج رابط إلى المرجع داخل أحد تطبيقات Google Workspace. لمزيد من المعلومات، اطّلِع على إنشاء مراجع تابعة لجهات خارجية من قائمة @.