على المستخدمين السماح للإضافات والتطبيقات الأخرى التي يمكنها الوصول إلى بياناتهم أو التصرف نيابةً عنه. عندما يشغّل المستخدم إضافة لأول مرة، واجهة مستخدم الإضافة تطلب الحصول على الإذن لبدء مسار التفويض
أثناء هذا التدفق، تخبر المطالبة المستخدم بما يريده التطبيق إذن بالقيام به. على سبيل المثال، قد تحتاج إحدى الإضافات إلى إذن لقراءة المستخدم أو إنشاء أحداث في التقويم. النص البرمجي للإضافة مشروعك هذه الأذونات الفردية كـ نطاقات OAuth.
أن تشير إلى النطاقات في بيانك
باستخدام سلاسل عناوين URL. أثناء تدفق التفويض، تعرض "برمجة تطبيقات Google"
وصف النطاق سهل القراءة للمستخدم. على سبيل المثال، إضافة Google Workspace
قد يتم استخدام زر "قراءة الرسالة الحالية" النطاق، والذي تمت كتابته في البيان على أنه
https://www.googleapis.com/auth/gmail.addons.current.message.readonly
خلال
تدفق التفويض، حيث تطلب إضافة بهذا النطاق من المستخدم السماح
الإضافة إلى: عرض الرسائل الإلكترونية عند تشغيل الإضافة.
نطاق العرض
يمكنك معرفة النطاقات التي يتطلبها مشروع النص البرمجي حاليًا من خلال تنفيذ التالي:
- افتح مشروع النص البرمجي.
- على يمين الصفحة، انقر على نظرة عامة.
- اطّلِع على النطاقات ضمن "نطاقات OAuth للمشروع".
يمكنك أيضًا عرض النطاقات الحالية لمشروع النص البرمجي في بيان المشروع،
ضمن oauthScopes
ولكن فقط في حال تحديد هذه النطاقات بشكل صريح.
إعداد نطاقات صريحة
تحدِّد "برمجة تطبيقات Google" تلقائيًا النطاقات التي يحتاجها النص البرمجي من خلال الفحص التعليمة البرمجية لاستدعاءات الدوال التي تتطلبها. بالنسبة لمعظم النصوص البرمجية هذا هو بشكل كافٍ ويوفر عليك الوقت، ولكن مع الإضافات المنشورة، عليك ممارسة المزيد من التحكم المباشر في النطاقات.
على سبيل المثال، قد تمنح "برمجة تطبيقات Google" مشروع النص البرمجي الإضافي مستوى التساهل للغاية
النطاق https://mail.google.com
افتراضيًا. عندما يفوّض المستخدم نصًا برمجيًا
بهذا النطاق، يتم منح المشروع إذن الوصول الكامل إلى حساب Gmail الخاص بالمستخدم
الحساب. بالنسبة إلى الإضافات المنشورة، يجب استبدال هذا النطاق
محدودة تغطي احتياجات الوظائف الإضافية وليس أكثر.
يمكنك تحديد النطاقات التي يستخدمها مشروع النص البرمجي بشكل صريح عن طريق التعديل
ملف البيان الخاص به. حقل البيان
oauthScopes
عبارة عن صفيف
جميع النطاقات التي تستخدمها الإضافة. لتعيين نطاقات مشروعك، قم
التالي:
- اطّلِع على النطاقات التي تستخدمها الإضافة حاليًا. حدد ما الذي يجب إجراء تغييرات، مثل استخدام نطاق أضيق.
- افتح ملف بيان الإضافة.
- حدِّد موقع حقل المستوى الأعلى المسمى
oauthScopes
. إذا لم تكن موجودة، فيمكنك إضافتها. oauthScopes
صفيفًا من السلاسل. لإعداد النطاقات يستخدمه مشروعك، استبدل محتوى هذه الصفيفة بالنطاقات التي نريد استخدامها. على سبيل المثال، بالنسبة إلى إضافة Google Workspace التي تعمل على توسيع نطاق Gmail، قد يكون لديك ما يلي:{ ... "oauthScopes": [ "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email" ], ... }
احفظ التغييرات التي تم إجراؤها على ملف البيان.
التحقّق من OAuth
قد يتطلب استخدام بعض نطاقات OAuth الحساسة تنفيذ الإضافة التحقّق من عميل OAuth قبل أن تتمكّن من نشره لمزيد من المعلومات، يُرجى الاطّلاع على الأدلة التالية:
- التحقق من عميل OAuth لبرمجة التطبيقات
- التطبيقات التي لم يتم التحقّق منها
- الأسئلة الشائعة حول إثبات الملكية باستخدام OAuth
- خدمة Google APIs: سياسة بيانات المستخدمين
النطاقات المشروطة
تكون بعض النطاقات مقيَّدة وتخضع لقواعد إضافية تساعد في وحماية بيانات المستخدم. إذا كنت تنوي نشر إضافة Gmail أو "محرّر إعلانات Google" تستخدم نطاق مقيّد واحد أو أكثر، يجب أن تلتزم الإضافة بجميع قبل نشره.
راجِع القائمة الكاملة للنطاقات المحظورة. قبل محاولة النشر إذا كانت الإضافة تستخدم أيًا منها، عليك الالتزام مع متطلبات إضافية لنطاقات محدّدة لواجهة برمجة التطبيقات قبل النشر.
نطاقات التقويم
في ما يلي النطاقات المستخدمة بشكل متكرر لإضافات Google Workspace التي توسِّع "تقويم Google".
النطاق | |
---|---|
الوصول إلى البيانات الوصفية للحدث |
https://www.googleapis.com/auth/calendar.addons.execute
مطلوب في حال وصول الإضافة إلى البيانات الوصفية لحدث "تقويم Google". تسمح الوظيفة الإضافية للوصول إلى البيانات الوصفية للحدث. |
قراءة بيانات الأحداث من إنشاء المستخدمين |
https://www.googleapis.com/auth/calendar.addons.current.event.read
مطلوبة إذا كانت الإضافة تحتاج إلى قراءة بيانات الأحداث من إنشاء المستخدمين.
تسمح للإضافة بالوصول إلى بيانات الأحداث من إنشاء المستخدمين. هذه البيانات
متاحة فقط إذا
حقل البيان |
كتابة بيانات الأحداث من إنشاء المستخدمين |
https://www.googleapis.com/auth/calendar.addons.current.event.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" |
https://www.googleapis.com/auth/documents.currentonly
مطلوب إذا كانت الإضافة تصل إلى واجهة برمجة تطبيقات مستندات برمجة التطبيقات. يمنح حق الوصول المؤقت إلى محتوى المستند المفتوح. |
الوصول الحالي إلى ملفات "جداول بيانات Google" |
https://www.googleapis.com/auth/spreadsheets.currentonly
مطلوب إذا كانت الإضافة تصل إلى واجهة برمجة تطبيقات جداول بيانات برمجة التطبيقات. يمنح حق الوصول المؤقت إلى محتوى جدول البيانات المفتوح. |
الإذن بالوصول الحالي إلى ملفات "العروض التقديمية من Google" |
https://www.googleapis.com/auth/presentations.currentonly
مطلوب إذا كانت الإضافة تصل إلى واجهة برمجة تطبيقات العروض التقديمية لبرمجة التطبيقات. يمنح حق الوصول المؤقت إلى محتوى العرض التقديمي المفتوح. |
الوصول لكل ملف |
https://www.googleapis.com/auth/drive.file
مطلوبة للإضافة لاستخدام |
النطاقات الأخرى
قد تتطلب الإضافة نطاقات إضافية في حال كانت تستخدم خدمات "برمجة تطبيقات Google" الأخرى. في معظم الحالات، يمكنك السماح لـ "برمجة التطبيقات" برصد هذه النطاقات وتعديل البيانات تلقائيًا. عند تعديل قائمة نطاقات البيان، يجب عدم الإزالة أي نطاقات ما لم تستبدلها ببديل أكثر ملاءمة، مثل نطاق أضيق.
إليك قائمة بنطاقات برمجة التطبيقات التي تُستخدم غالبًا في إلى جانب إضافات Google Workspace:
النطاق | |
---|---|
قراءة عنوان البريد الإلكتروني للمستخدم |
https://www.googleapis.com/auth/userinfo.email
يسمح هذا الإذن للمشروع بقراءة عنوان البريد الإلكتروني للمستخدم الحالي. |
السماح بالمكالمات لخدمات خارجية |
https://www.googleapis.com/auth/script.external_request
يسمح للمشروع بإجراء
|
قراءة لغة المستخدم والمنطقة الزمنية |
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. لمزيد من المعلومات، راجع يمكنك إنشاء موارد تابعة لجهات خارجية من قائمة @. |