تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

المناظير

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

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

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

عرض النطاقات

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

افتح مشروع النص البرمجي.
على يمين الصفحة، انقر على نظرة عامة.
اطّلِع على النطاقات ضمن "نطاقات OAuth للمشروع".

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

ضبط نطاقات صريحة

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

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

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

تكون بعض النطاقات محظورة وتخضع لقواعد إضافية تساعد في حماية بيانات المستخدمين. إذا كنت تنوي نشر إضافة 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 . يمنح الإذن بالوصول لكل ملف إلى الملفات التي ينشئها التطبيق أو فتحها باستخدام برمجة التطبيقات Drive المتقدم الخدمة: ومع ذلك، لا يسمح هذا الإجراء باستخدام إجراءات مشابهة باستخدام خدمة 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 للمساعدة في حماية 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` قراءة أي بيانات وصفية أو محتوى للرسائل الإلكترونية، بما في ذلك الرسالة المفتوحة مطلوبة إذا كنت بحاجة إلى قراءة معلومات عن رسائل أخرى، مثل عند إجراء طلب بحث أو قراءة سلسلة رسائل بريد بالكامل. تحذير: هذا نطاق واسع جدًا، محدود. لا تستخدِمه إلا إذا كان ضروريًا للغاية.

رموز الدخول

لحماية بيانات المستخدمين، لا تمنح نطاقات Gmail المستخدَمة في تطبيقات Google Workspace Add-ons سوى إذن بالوصول المؤقت إلى بيانات المستخدمين. لتفعيل الوصول المؤقت، يجب الاتصال الدالة 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` مطلوب إذا كانت الإضافة تصل إلى Apps Script Docs API يمنح هذا الإذن إذن وصول مؤقت إلى محتوى المستند المفتوح.
الوصول إلى ملف "جداول بيانات Google" الحالي	`https://www.googleapis.com/auth/spreadsheets.currentonly` مطلوب إذا كانت الإضافة تصل إلى واجهة برمجة تطبيقات جداول بيانات برمجة التطبيقات. يمنح هذا الإذن إذن وصول مؤقت إلى محتوى جدول البيانات المفتوح.
الإذن بالوصول الحالي إلى ملفات "العروض التقديمية من Google"	`https://www.googleapis.com/auth/presentations.currentonly` مطلوبة إذا كانت الإضافة تصل إلى واجهة برمجة التطبيقات Slides API في Apps Script يمنح هذا الإذن إمكانية الوصول المؤقت إلى محتوى العرض التقديمي المفتوح.
الوصول لكل ملف	`https://www.googleapis.com/auth/drive.file` مطلوبة للإضافة لاستخدام `onFileScopeGrantedTrigger` ووصول الإضافة إلى "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو Drive API يمنح الإذن بالوصول لكل ملف إلى الملفات التي ينشئها التطبيق أو فتحها باستخدام برمجة التطبيقات Drive المتقدم الخدمة: ومع ذلك، لا يسمح هذا الإجراء باستخدام إجراءات مشابهة باستخدام خدمة Drive الأساسية. يتم منح تفويض الملفات على أساس كل ملف يتم إبطالها عندما يُلغي المستخدم مصادقة التطبيق.

النطاقات الأخرى

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

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