المستويات

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

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

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

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

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

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

التحقّق من OAuth

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

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

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

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

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

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

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

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

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

النطاق
الوصول إلى ملفات "مستندات Google" الحالية https://www.googleapis.com/auth/documents.currentonly

مطلوب إذا كانت الإضافة تصل إلى Google Apps Script Docs API. يمنح إذن الوصول المؤقت إلى محتوى المستند المفتوح.

الوصول إلى ملفات "جداول بيانات Google" الحالية https://www.googleapis.com/auth/spreadsheets.currentonly

مطلوب إذا كانت الإضافة تصل إلى Sheets API في "برمجة التطبيقات". يمنح إذن الوصول المؤقت إلى محتوى جدول البيانات المفتوح.

الوصول إلى ملف "الشرائح الحالية" https://www.googleapis.com/auth/presentations.currentonly

مطلوب إذا كانت الإضافة تصل إلى برمجة تطبيقات Slides API. يمنح هذا الإذن إمكانية الوصول المؤقت إلى محتوى العرض التقديمي المفتوح.

الوصول إلى كل ملف على حدة https://www.googleapis.com/auth/drive.file

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

Gmail

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

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

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

النطاق
صياغة مسودّات جديدة https://www.googleapis.com/auth/gmail.addons.current.action.compose

مطلوب إذا كانت الإضافة تستخدم مشغّلات إجراءات الإنشاء. يسمح هذا الإذن للإضافة بإنشاء مسودات جديدة للرسائل والردود بشكل مؤقت. راجِع إنشاء مسودات رسائل للحصول على التفاصيل. غالبًا ما يُستخدَم هذا النطاق مع [إجراءات الإنشاء] (/workspace/add-ons/gmail/extending-compose-ui). يتطلّب ذلك رمز دخول.

قراءة البيانات الوصفية للرسائل المفتوحة 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

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

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

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

الطريقة مصادقة المستخدم متاحة مصادقة التطبيق متاحة نطاقات الأذونات المتاحة
إرسال رسالة باستخدام مصادقة المستخدم:
  • chat.messages.create
  • chat.messages
  • chat.import
باستخدام مصادقة التطبيق:
  • chat.bot
إنشاء مساحة باستخدام مصادقة المستخدم:
  • chat.spaces.create
  • chat.spaces
  • chat.import
باستخدام مصادقة التطبيق وموافقة المشرف (المتاحتَين في معاينة المطوّر):
  • chat.app.spaces.create
  • chat.app.spaces
إنشاء مساحة وإضافة أعضاء إليها — باستخدام مصادقة المستخدم:
  • chat.spaces.create
  • chat.spaces
إضافة مستخدم إلى مساحة باستخدام مصادقة المستخدم:
  • chat.memberships
  • chat.memberships.app
  • chat.import
باستخدام مصادقة التطبيق وموافقة المشرف (المتاحتَين في معاينة المطوّر):
  • 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 المتقدّمة في "برمجة تطبيقات Google". ولا يسمح ذلك باتّخاذ إجراءات مشابهة باستخدام خدمة Drive الأساسية. يتم منح إذن الوصول إلى الملفات على أساس كل ملف على حدة، ويتم إبطاله عندما يلغي المستخدم تفويض التطبيق. راجِع مثال طلب الوصول إلى الملفات المحدّدة.

رموز الدخول

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

إنّ رمز الدخول الذي يتيح نطاقات 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 أو برمجة تطبيقات. في معظم الحالات، يرصد برمجة تطبيقات هذه النطاقات ويعدّل البيان تلقائيًا. عند تعديل قائمة النطاقات في ملف البيان، لا تزِل أي نطاقات إلا إذا كنت ستستبدلها بنطاق بديل أضيق.

يعرض الجدول التالي النطاقات التي تستخدمها إضافات 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. لمزيد من المعلومات، اطّلِع على المقالة إنشاء مراجع خارجية من قائمة @.