التفويض لخدمات Google

تتطلّب "برمجة تطبيقات Google" إذن وصول من المستخدم للوصول إلى البيانات الخاصة من خدمات Google المضمّنة أو خدمات Google المتقدّمة.

آلية عمل أذونات الوصول لخدمات Google

عندما يحتاج نص برمجي إلى الوصول إلى خدمات Google، يتّبع العملية العامة التالية:

1. الكشف: تفحص "برمجة تطبيقات Google" النص البرمجي لتحديد الخدمات التي يستخدمها (على سبيل المثال، SpreadsheetApp أو GmailApp).
2. تحديد النطاق: استنادًا إلى الفحص، تحدّد "برمجة تطبيقات Google" مجموعة من نطاقات OAuth اللازمة لتشغيل النص البرمجي.
3. التحقّق من إذن الوصول: عند تشغيل النص البرمجي، يتم التحقّق مما إذا كان المستخدم قد منح إذن الوصول إلى هذه النطاقات من قبل.
4. مطالبة المستخدم: إذا لم يتم منح إذن الوصول، يظهر مربّع حوار يطلب من المستخدم منح الإذن.
5. التنفيذ: بعد منح إذن الوصول إلى النص البرمجي، يمكنه الوصول إلى البيانات المطلوبة لهذا المستخدم.

الأذونات وأنواع النصوص البرمجية

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

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

منح حقوق الوصول

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

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

**تحذير:** تخضع تطبيقات الويب والنصوص البرمجية الأخرى التي تستخدم نطاقات حساسة للمراجعة من قِبل Google. قد يرى المستخدمون الذين يحاولون منح إذن الوصول إلى هذه التطبيقات شاشة تحذير تشير إلى أنّ Google لم تتحقّق من التطبيق. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة التحقّق من عميل OAuth.

إبطال حقوق الوصول

لإبطال إذن وصول نص برمجي إلى بياناتك، اتّبِع الخطوات التالية:

1. انتقِل إلى قسم "الأمان" في حسابك على Google.
2. ضمن عمليات الربط بالتطبيقات والخدمات التابعة لجهات خارجية ، انقر على عرض كل عمليات الربط.
3. اختَر النص البرمجي أو التطبيق الذي تريد إبطال إذن الوصول إليه.
4. انقر على إلغاء كل عمليات الربط بين حسابك وAPP_NAME، ثم انقر على تأكيد.

حصر النطاق على المستند الحالي

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

/**
 * @OnlyCurrentDoc
 */

يتوفّر تعليق توضيحي معاكس، وهو @NotOnlyCurrentDoc، إذا كان النص البرمجي يتضمّن مكتبة تعرِض @OnlyCurrentDoc، ولكن النص البرمجي الأساسي يتطلّب في الواقع الوصول إلى أكثر من الملف الحالي.

دورة حياة أذونات الوصول للإضافات

تتّبع إضافات "جداول بيانات Google"، "مستندات Google" و"العروض التقديمية من Google" و"نماذج Google" بشكل عام نموذج أذونات الوصول نفسه الذي تتّبعه النصوص البرمجية التي تكون مرتبطة بمستند. ومع ذلك، في ظروف معيّنة، يتم تشغيل وظيفتَي onOpen(e) وonEdit(e) في وضع بدون إذن وصول يطرح بعض المشاكل الإضافية. لمزيد من المعلومات، يُرجى الاطّلاع على دليل دورة حياة أذونات الإضافات.

حدود المستخدمين لتطبيقات OAuth

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

سلوك إعادة المصادقة في "برمجة تطبيقات Google"

لا تفرض "برمجة تطبيقات Google" وتيرة إعادة المصادقة التي تم ضبطها في إعدادات خدمة Google Cloud. يرجع ذلك إلى إمكانية تشغيل "برمجة تطبيقات Google" تلقائيًا باستخدام المشغّلات التي تعمل بدون تفاعل مباشر من المستخدم. لا تؤدي عمليات التنفيذ الآلية هذه إلى ظهور مطالبات إعادة المصادقة. لا يطلب تطبيق "برمجة تطبيقات Google" تلقائيًا إعادة المصادقة بعد الفترة الزمنية المحدّدة (على سبيل المثال، 12 ساعة).

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

تحدّد "برمجة تطبيقات Google" النطاقات المطلوبة تلقائيًا من خلال فحص الرمز بحثًا عن استدعاءات الدوال. إذا كنت بحاجة إلى مزيد من التحكّم، يمكنك ضبط النطاقات بشكل صريح في بيان المشروع (appsscript.json). يُنصح بذلك للنصوص البرمجية المنشورة لضمان استخدام الحد الأدنى من الأذونات المطلوبة.

للحصول على التعليمات، يُرجى الاطّلاع على مقالة ضبط نطاقات صريحة.

تحديد المشاكل وحلّها

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