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

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

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

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

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

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

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

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

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

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

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

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

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

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

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