المناظير

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

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

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

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

نطاقات العرض

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

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 قبل أن تتمكّن من نشرها. لمزيد من المعلومات، يُرجى الاطّلاع على الأدلة التالية:

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

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

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

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

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

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

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

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

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

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

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

Gmail

هناك بعض النطاقات التي تم إنشاؤها خصيصًا لإضافة Google Workspace للمساعدة في حماية data 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

إصدار المطوّر: يتوفّر كجزء من برنامج إصدار المطوّر في Google Workspace، الذي يتيح الوصول المبكر إلى ميزات معيّنة.

لطلب بيانات من Chat API، عليك المصادقة بصفته مستخدم Google Chat أو تطبيق Chat. يتطلب كل نوع من أنواع المصادقة نطاقات مختلفة، ولا تتوافق بعض methods في 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 المتقدمة في "برمجة التطبيقات" ومع ذلك، لا يسمح هذا الإجراء باستخدام إجراءات مشابهة باستخدام خدمة 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 لـ Apps Script.
قراءة لغة المستخدم والمنطقة الزمنية	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 لمزيد من المعلومات، يُرجى الاطّلاع على المقالة إنشاء موارد تابعة لجهات خارجية من قائمة @.