المناظير

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

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

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

عرض النطاقات

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

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

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

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

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

نطاقات "تقويم 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.

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

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

رموز الدخول

لحماية بيانات المستخدمين، لا تمنح نطاقات 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" و"جداول بيانات Google" و"العروض التقديمية من Google".

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

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

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

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

الوصول الحالي إلى ملف "العروض التقديمية من Google" https://www.googleapis.com/auth/presentations.currentonly

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

الوصول لكل ملف https://www.googleapis.com/auth/drive.file

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

نطاقات أخرى

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

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