المستويات

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

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

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

نطاقات العرض

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

  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

مطلوب إذا كانت الإضافة تصل إلى واجهة برمجة التطبيقات 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
باستخدام مصادقة التطبيق وموافقة المشرف (المتاحتَين في معاينة المطوّر):
  • 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 المتقدّمة في Apps Script. ولا يسمح هذا الإذن باستخدام إجراءات مشابهة باستخدام خدمة Drive الأساسية. يتم منح إذن الوصول إلى الملفات على أساس كل ملف على حدة، ويتم إبطاله عندما يلغي المستخدم تفويض التطبيق.

راجِع مثال طلب الوصول إلى الملفات المحدّدة.

رموز الدخول

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

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