حتى أكثر المطورين خبرة نادرًا ما يكتب التعليمات البرمجية بشكل صحيح في المحاولة الأولى، مما يجعل استكشاف الأخطاء وإصلاحها جزءًا مهمًا من عملية التطوير. سنتناول في هذا القسم بعض الأساليب التي يمكن أن تساعدك في العثور على الأخطاء في النصوص البرمجية وفهمها وتصحيحها.
رسائل الخطأ
عندما يواجه النص البرمجي خطأً، يتم عرض رسالة خطأ. تكون الرسالة مصحوبة برقم سطر يُستخدم لتحديد المشاكل وحلّها. هناك نوعان أساسيان من الأخطاء يتم عرضهما بهذه الطريقة: أخطاء البنية وأخطاء وقت التشغيل.
أخطاء في البنية
تحدث أخطاء البنية بسبب كتابة رمز لا يتّبع القواعد النحوية بلغة JavaScript، ويتم اكتشاف الأخطاء بمجرد محاولة حفظ النص البرمجي. على سبيل المثال، يحتوي مقتطف الرمز التالي على خطأ في البنية:
function emailDataRow(rowNumber) {
var sheet = SpreadsheetApp.getActiveSheet();
var data = sheet.getDataRange().getValues();
var rowData = data[rowNumber-1].join(" ";
MailApp.sendEmail('john@example.com',
'Data in row ' + rowNumber,
rowData);
}
مشكلة الصيغة هنا هي وجود حرف ) مفقود في نهاية السطر الرابع. عندما تحاول حفظ النص البرمجي، سيظهر لك الخطأ التالي:
) غير متوفر بعد قائمة الوسيطات. (السطر 4)
عادةً ما يسهل استكشاف هذه الأنواع من الأخطاء وإصلاحها، نظرًا لأنها موجودة على الفور وعادةً ما يكون لها أسباب بسيطة. ولا يمكنك حفظ ملف يحتوي على أخطاء في بناء الجملة، مما يعني أنه يتم حفظ التعليمات البرمجية الصالحة فقط في مشروعك.
أخطاء في وقت التشغيل
تحدث هذه الأخطاء بسبب استخدام دالة أو فئة بشكل غير صحيح، ولا يمكن رصدها إلا بعد تشغيل النص البرمجي. على سبيل المثال، تتسبب التعليمة البرمجية التالية في حدوث خطأ في وقت التشغيل:
function emailDataRow(rowNumber) {
var sheet = SpreadsheetApp.getActiveSheet();
var data = sheet.getDataRange().getValues();
var rowData = data[rowNumber-1].join(" ");
MailApp.sendEmail('john',
'Data in row ' + rowNumber,
rowData);
}
تم تنسيق الرمز بشكل صحيح، لكننا نمرر القيمة "جون" لعنوان البريد الإلكتروني عند استدعاء MailApp.sendEmail. نظرًا لأن هذا ليس عنوان بريد إلكتروني صالحًا، يتم عرض الخطأ التالي عند تشغيل النص البرمجي:
بريد إلكتروني غير صالح: هاني (السطر 5)
ما يجعل استكشاف الأخطاء وإصلاحها أكثر صعوبة هو أنه في كثير من الأحيان لا تتم كتابة البيانات التي تمررها إلى دالة في التعليمات البرمجية، ولكن بدلاً من ذلك يتم سحبها من جدول بيانات أو نموذج أو مصدر بيانات خارجي آخر. ويمكن أن يساعدك استخدام أساليب تصحيح الأخطاء أدناه في تحديد سبب هذه الأخطاء.
الأخطاء الشائعة
في ما يلي قائمة بالأخطاء الشائعة وأسبابها.
تم استدعاء الخدمة مرات كثيرة جدًا: <action name>
يشير هذا الخطأ إلى أنّك تجاوزت حصتك اليومية لإجراء معيّن. على سبيل المثال، قد تواجه هذا الخطأ إذا أرسلت عددًا كبيرًا جدًا من رسائل البريد الإلكتروني في يوم واحد. يتمّ ضبط الحصص على مستويات مختلفة لحسابات المستهلكين والنطاق والحساب المميّز، وهي عرضة للتغيير في أي وقت بدون إشعار مسبق من Google. يمكنك الاطّلاع على حدود الحصة لإجراءات متنوعة من خلال مستندات حصة برمجة التطبيقات.
الخادم غير متاح. أو حدث خطأ في الخادم. يُرجى إعادة المحاولة.
هناك بضعة أسباب محتملة لهذه الأخطاء:
- خادم أو نظام Google غير متاح مؤقتًا. انتظر بضع لحظات وحاول تشغيل النص البرمجي مرة أخرى.
- هناك خطأ في النص البرمجي لا يحتوي على رسالة خطأ مقابلة. جرِّب تصحيح الأخطاء في النص البرمجي لمعرفة ما إذا كان بإمكانك عزل المشكلة.
- هناك خطأ في "برمجة تطبيقات Google" يتسبب في هذا الخطأ. للحصول على تعليمات حول البحث عن تقارير الأخطاء وتقديمها، يمكنك الاطّلاع على الأخطاء. قبل تقديم خطأ جديد، ابحث عنه لمعرفة ما إذا كان الآخرون قد أبلغوا عنه بالفعل.
يجب الحصول على إذن لتنفيذ هذا الإجراء.
يشير هذا الخطأ إلى أنّ النص البرمجي لا يملك الإذن اللازم للتشغيل. عند تشغيل نص برمجي في محرر النصوص البرمجية أو من عنصر قائمة مخصص، يتم عرض مربع حوار تفويض للمستخدم. أمّا عند تشغيل نص برمجي من مشغّل، أو مضمّن في صفحة "مواقع Google"، أو عند تشغيله كخدمة، فلا يمكن تقديم مربّع الحوار ويتم عرض هذا الخطأ.
لاعتماد النص البرمجي، افتح "محرِّر النصوص البرمجية" وشغِّل أي دالة. ستظهر رسالة التفويض حتى تتمكن من تفويض مشروع النص البرمجي. إذا كان النص البرمجي يحتوي على خدمات جديدة غير مصرَّح بها، عليك إعادة تفويض النص البرمجي.
وغالبًا ما يحدث هذا الخطأ بسبب العوامل المُشغِّلة التي يتم تنشيطها قبل أن يسمح المستخدم لها. إذا لم يكن لديك إمكانية الوصول إلى مشروع النص البرمجي (لأنّ الخطأ يحدث لإضافة تستخدمها، على سبيل المثال)، يمكنك عادةً تفويض النص البرمجي باستخدام الإضافة مرة أخرى. إذا استمر تنشيط المشغل وتسبب هذا الخطأ، يمكنك إزالة المشغلات عن طريق إجراء ما يلي:
- على يمين مشروع "برمجة التطبيقات"، انقر على العوامل المشغِّلة .
- على يسار المشغِّل الذي تريد إزالته، انقر على رمز المزيد > حذف المشغِّل.
يمكنك أيضًا إزالة مشغِّلات الإضافات التي بها مشاكل من خلال إلغاء تثبيت الإضافة.
تم رفض الوصول: DriveApp أو أوقفت سياسة النطاق تطبيقات Drive التابعة لجهة خارجية
يمكن لمشرفي Google Workspace النطاقات إيقاف Drive API لنطاقهم، ما يمنع المستخدمين من تثبيت تطبيقات Google Drive واستخدامها. يمنع هذا الإعداد أيضًا المستخدمين من استخدام إضافات "برمجة التطبيقات" التي تستخدم خدمة Drive أو خدمة Drive المتقدّمة (حتى إذا تم السماح بالنص البرمجي قبل إيقاف المشرف لواجهة Drive API).
ومع ذلك، إذا تم نشر إضافة أو تطبيق ويب يستخدم خدمة Drive من أجل التثبيت على مستوى النطاق وتثبيته المشرف لبعض المستخدمين في النطاق أو جميعهم، ستعمل وظائف النص البرمجي لهؤلاء المستخدمين حتى إذا كانت واجهة برمجة تطبيقات Drive غير مفعّلة في النطاق.
لا يملك النص البرمجي إذنًا للوصول إلى هوية المستخدم النشط.
يشير إلى أن هوية المستخدم النشط وعنوان بريده الإلكتروني غير متاحين للنص البرمجي. ينتج هذا التحذير عن اتصال بالطلب على Session.getActiveUser().
ويمكن أن ينتج أيضًا عن استدعاء إلى
Session.getEffectiveUser()
إذا كان النص البرمجي يعمل في وضع تفويض بخلاف
AuthMode.FULL.
إذا تمت الإشارة إلى هذا التحذير، لن تعرض الطلبات اللاحقة إلى User.getEmail() إلا "".
هناك عدّة طرق لتحديد مشاكل هذا التحذير وحلّها، استنادًا إلى وضع التفويض الذي يعمل النصّ البرمجي فيه. يظهر وضع التفويض في الدوال المُشغّلة بصفتها خاصية authMode e
لمَعلمة الحدث.
- في
AuthMode.FULL، يمكنك استخدامSession.getEffectiveUser()بدلاً من ذلك. - في
AuthMode.LIMITED، تأكَّد من أنّ المالك قد فوّض الإذن بالنص البرمجي. - في أوضاع التفويض الأخرى، تجنَّب طلب أيٍّ من الطريقتَين.
- إذا كنت Google Workspace عميلاً واجه مؤخرًا هذا التحذير من مشغّل قابل للتثبيت، تأكَّد من أنّ عامل التفعيل يعمل كمستخدم داخل مؤسستك.
المكتبة غير متوفّرة
إذا أضفت مكتبة شائعة إلى النص البرمجي، قد تتلقى رسالة خطأ تفيد بأنّ هذه المكتبة غير متوفرة، حتى لو تم إدراج المكتبة كتبعية للنص البرمجي الخاص بك. قد يكون السبب هو أن عددًا كبيرًا جدًا من الأشخاص يصلون إلى المكتبة في الوقت نفسه. لتجنُّب هذا الخطأ، جرِّب أحد الحلول التالية:
- انسخ رمز المكتبة والصقه في النص البرمجي وإزالة تبعية المكتبة.
- انسخ النص البرمجي للمكتبة وانشره كمكتبة من حسابك. تأكد من تحديث التبعية في النص الأصلي إلى المكتبة الجديدة بدلاً من المكتبة العامة.
حدث خطأ بسبب عدم توفّر إصدار مكتبة أو إصدار نشر. رمز الخطأ Not_Found
تشير رسالة الخطأ هذه إلى أي مما يلي:
- تم حذف النسخة المنشورة من النص البرمجي. لتعديل الإصدار المنشور من النص البرمجي، يُرجى الاطّلاع على تعديل عملية نشر متعدّدة النُسخ.
- تم حذف نسخة المكتبة التي يستخدمها النص البرمجي. لمعرفة المكتبة المفقودة، انقر على
المزيد
> فتح في علامة تبويب جديدة بجانب اسم المكتبة. تعرض المكتبة المفقودة
رسالة خطأ. بعد العثور على المكتبة التي تريد تحديثها، يمكنك اتخاذ أحد الإجراءات التالية:
- يُرجى تحديث المكتبة لاستخدام إصدار مختلف. راجِع تحديث مكتبة.
- عليك إزالة المكتبة المحذوفة من مشروع النص البرمجي ورمزه. يُرجى الاطّلاع على المقالة إزالة مكتبة.
- يشتمل النص البرمجي للمكتبة التي يستخدمها النص البرمجي على مكتبة أخرى تستخدم نسخة محذوفة. يُرجى اتّخاذ أحد الإجراءات التالية:
- إذا كان لديك الإذن بتعديل المكتبة التي يستخدمها النص البرمجي، عليك تعديل المكتبة الثانوية في هذا النص البرمجي إلى نسخة حالية.
- يُرجى تحديث المكتبة لاستخدام إصدار مختلف. راجِع تحديث مكتبة.
- عليك إزالة المكتبة من مشروع النص البرمجي والرمز البرمجي. يُرجى الاطّلاع على المقالة إزالة مكتبة.
Error 400: invalid_scope عند طلب البيانات من Google Chat API باستخدام الخدمة المتقدّمة
إذا ظهرت لك رسالة الخطأ Error 400: invalid_scope
Some requested scopes cannot be shown، هذا يعني أنّه لم يتم تحديد أي نطاقات تفويض في ملف appsscript.json لمشروع "برمجة التطبيقات". في معظم الحالات،
تحدِّد لغة "برمجة تطبيقات Google" تلقائيًا النطاقات التي يحتاجها النص البرمجي،
ولكن عند استخدام خدمة Chat المتقدّمة، عليك إضافة
نطاقات التفويض التي يستخدمها النص البرمجي يدويًا إلى
ملف بيان مشروع "برمجة التطبيقات". يُرجى الاطّلاع على
إعداد النطاقات الصريحة.
لحل الخطأ، أضِف نطاقات التفويض المناسبة إلى ملف appsscript.json لمشروع "برمجة التطبيقات" كجزء من مصفوفة oauthScopes. على سبيل المثال، لطلب الإجراء
spaces.messages.create،
أضِف ما يلي:
"oauthScopes": [
"https://www.googleapis.com/auth/chat.messages.create"
]
تصحيح الأخطاء
لا تؤدي جميع الأخطاء إلى عرض رسالة خطأ. قد يكون هناك خطأ أكثر دقة حيث تكون التعليمة البرمجية صحيحة من الناحية الفنية ويمكن تنفيذها، لكن النتائج ليست ما تتوقعه. إليك بعض الاستراتيجيات للتعامل مع مثل هذه المواقف وإجراء المزيد من التحقيق في نص برمجي لا يعمل بالطريقة التي تتوقعها.
التسجيل
أثناء تصحيح الأخطاء، غالبًا ما يكون من المفيد تسجيل المعلومات أثناء تنفيذ مشروع نص برمجي. هناك طريقتان لتسجيل المعلومات في "برمجة تطبيقات Google" وهما: خدمة التسجيل في السحابة الإلكترونية وخدمات التسجيل ووحدة التحكم الأساسية المدمَجة في أداة تعديل "برمجة تطبيقات Google".
راجِع دليل التسجيل للحصول على مزيد من التفاصيل.
Error Reporting
ويتم تسجيل الاستثناءات التي تحدث بسبب أخطاء وقت التشغيل تلقائيًا باستخدام خدمة "إعداد تقارير الأخطاء في Google Cloud". تتيح لك هذه الخدمة البحث عن الرسائل الاستثنائية التي ينشئها مشروع النص البرمجي وتصفيتها.
للوصول إلى "إعداد تقارير الأخطاء"، يُرجى الاطّلاع على عرض سجلّات Cloud وتقارير الأخطاء في وحدة تحكُّم Google Cloud Platform.
عمليات التنفيذ
في كل مرة يتم فيها تشغيل نص برمجي، تسجِّل "برمجة التطبيقات" سجلاً لعملية التنفيذ، بما في ذلك سجلات Cloud. ويمكن أن تساعدك هذه السجلات على فهم الإجراءات التي نفذها النص البرمجي.
للاطّلاع على عمليات تنفيذ النص البرمجي في مشروع "برمجة التطبيقات"، انقر على عمليات التنفيذ على يمين الصفحة.
جارٍ التحقّق من حالة خدمة "برمجة تطبيقات Google"
تواجه خدمات Google Workspace (مثل Gmail أو Drive) مشاكل مؤقتة يمكن أن تؤدي إلى انقطاع الخدمة، على الرغم من ندرة ذلك. وعند حدوث ذلك، قد لا تعمل مشاريع "برمجة التطبيقات" التي تتفاعل مع هذه الخدمات على النحو المتوقَّع.
ويمكنك التحقّق مما إذا كان هناك انقطاع في خدمة Google Workspace من خلال الاطّلاع على لوحة بيانات حالة Google Workspace. في حال حدوث انقطاع في الخدمة حاليًا، عليك الانتظار إلى أن يتم حلّه أو طلب مساعدة إضافية في مركز مساعدة Google Workspace أو مستندات المشاكل المعروفة في Google Workspace.
استخدام برنامج تصحيح الأخطاء ونقاط الإيقاف
لتحديد المشاكل في النص البرمجي، يمكنك تشغيله في وضع تصحيح الأخطاء. عند تشغيل النص في وضع تصحيح الأخطاء، يتوقف النص البرمجي مؤقتًا عند الوصول إلى نقطة توقف، وهي السطر الذي حددته في النص البرمجي وتعتقد أنه قد يواجه مشكلة. عندما يتوقف النص البرمجي مؤقتًا، فإنه يعرض قيمة كل متغير في هذه المرحلة الزمنية، ما يسمح لك بفحص الأعمال الداخلية للنص البرمجي بدون الحاجة إلى إضافة الكثير من عبارات التسجيل.
إضافة نقطة إيقاف
لإضافة نقطة إيقاف، مرِّر مؤشر الماوس فوق رقم السطر الذي تريد إضافة نقطة الإيقاف إليه. على يمين رقم الخط، انقر على الدائرة. وتوضح الصورة أدناه مثالاً لنقطة إيقاف مضافة إلى نص برمجي:
تشغيل نص برمجي في وضع تصحيح الأخطاء
لتشغيل النص البرمجي في وضع تصحيح الأخطاء، انقر على تصحيح الأخطاء في أعلى المحرِّر.
قبل أن يشغّل النص البرمجي السطر الذي توجد فيه نقطة الإيقاف، يتوقف مؤقتًا ويعرض جدولاً يحتوي على معلومات تصحيح الأخطاء. يمكنك استخدام هذا الجدول لفحص البيانات، مثل قيم المَعلمات والمعلومات المخزَّنة في العناصر.
للتحكّم في كيفية تشغيل النص البرمجي، استخدِم الأزرار "تسجيل الدخول" و"تخطّي" و"الخروج" في أعلى لوحة "برنامج تصحيح الأخطاء". يتيح لك ذلك تشغيل النص البرمجي سطرًا واحدًا في كل مرة وفحص كيفية تغيّر القيم بمرور الوقت.
مشاكل في حسابات Google المتعددة
إذا سجّلت الدخول إلى حسابات متعددة على Google في الوقت نفسه، قد تواجه مشكلة في الوصول إلى الإضافات وتطبيقات الويب. لا يتوفر تسجيل الدخول المتعدد أو تسجيل الدخول إلى حسابات Google متعددة في وقت واحد مع برمجة التطبيقات أو الإضافات أو تطبيقات الويب.
إذا فتحت محرِّر "برمجة تطبيقات Google" وأنت مسجّل الدخول إلى أكثر من حساب واحد، ستطلب منك Google اختيار الحساب الذي تريد المتابعة من خلاله.
إذا فتحت تطبيق ويب أو إضافة وواجهت مشاكل في تسجيل الدخول المتعدد، جرِّب أحد الحلول التالية:
- سجِّل الخروج من جميع حسابات Google وسجِّل الدخول فقط إلى الحساب الذي يتضمن الإضافة أو تطبيق الويب المطلوب الوصول إليهما.
- افتح نافذة التصفح المتخفي في Google Chrome أو نافذة تصفح خاص مكافئة، وسجّل الدخول إلى حساب Google الذي يتضمن الإضافة أو تطبيق الويب الذي تريد الوصول إليه.
الحصول على المساعدة
يمكن أن يؤدي تصحيح الأخطاء باستخدام الأدوات والتقنيات المذكورة أعلاه إلى حل مجموعة متنوعة من المشكلات، ولكن قد تكون هناك مشكلات تواجهها وتتطلب بعض المساعدة الإضافية لحلها. راجع صفحة الدعم للحصول على معلومات حول مكان طرح الأسئلة والإبلاغ عن الأخطاء.