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

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

طريقة عمل أذونات الوصول إلى خدمات Google

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

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

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

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

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

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

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

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

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

إبطال أذونات الوصول

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

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

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

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

/**
 * @OnlyCurrentDoc
 */

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

مراحل ترخيص الإضافات

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

الحدود القصوى لعدد مستخدمي تطبيقات OAuth

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

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

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

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

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

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

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

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