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

المناظير

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

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

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

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

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