المناظير

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

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

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

نطاق العرض

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

1. افتح مشروع النص البرمجي.
2. على يمين الصفحة، انقر على نظرة عامة. info_outline
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 لبرمجة التطبيقات
• التطبيقات التي لم يتم التحقّق منها
• الأسئلة الشائعة حول إثبات الملكية باستخدام OAuth
• خدمة Google APIs: سياسة بيانات المستخدمين

النطاقات المشروطة

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

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

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

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

نطاقات Drive

في ما يلي النطاقات الأكثر استخدامًا لإضافات Google Workspace التي توسِّع Google Drive.

نطاقات إضافات Gmail

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

في ما يلي النطاقات المستخدمة بشكل متكرر لإضافات Google Workspace التي توسِّع Gmail. يجب إضافة تلك المذكورة إلى المطلوبة إلى بيان "إضافة Google Workspace" إذا كانت إضافتك موسّعة Gmail

تأكَّد أيضًا من استبدال نطاق https://mail.google.com الواسع جدًا في مع مجموعة أضيق من النطاقات التي تسمح بالتفاعلات مع إضافتك احتياجاتك وليس أكثر.

رموز الدخول

لحماية بيانات المستخدمين، تتضمن نطاقات 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 Workspace: