المناظير

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

عرض النطاقات

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

  1. افتح مشروع النص البرمجي.
  2. على يمين الصفحة، انقر على نظرة عامة .
  3. عرض النطاقات ضمن "Project OAuth Scopes&"

يمكنك أيضًا عرض نطاقات النص البرمجي الحالية في بيان المشروع، ضمن الحقل oauthScopes، ولكن فقط في حال ضبط هذه النطاقات بشكل صريح.

إعداد النطاقات الفاضحة

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

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

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

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

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

نطاقات التقويم

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

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

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

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

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

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

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

نطاقات أخرى

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

يمكنك الرجوع إلى القائمة "نطاقات برمجة التطبيقات" التي غالبًا ما تُستخدم مع "إضافات 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

تسمح للمشروع بإنشاء عوامل تشغيل.