المناظير

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

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

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

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

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