حتى المطوّر الأكثر خبرة نادرًا ما يكتب الرمز البرمجي بشكل صحيح في المرة الأولى، ما يجعل تحديد المشاكل وحلّها جزءًا مهمًا من عملية التطوير. في هذا القسم، سنتناول بعض الأساليب التي يمكن أن تساعدك في العثور على الأخطاء في النصوص البرمجية وفهمها و تصحيحها.
رسائل الخطأ
عندما يواجه النص البرمجي خطأ، يتم عرض رسالة خطأ. يتم إرفاق الرسالة برقم سطر يُستخدَم لتحديد المشاكل وحلّها. هناك نوعان أساسيان من الأخطاء التي يتم عرضها بهذه الطريقة: أخطاء البنية وأخطاء وقت التشغيل.
أخطاء في البنية
تحدث أخطاء البنية بسبب كتابة رمز لا يتّبع قواعد نحو 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);
}
تم تنسيق الرمز بشكل صحيح، ولكننا نُرسل القيمة "john" لعنوان البريد الإلكتروني عند الاتصال بالرقم MailApp.sendEmail. نظرًا لأن هذا ليس عنوان بريد إلكتروني صالحًا، يتم عرض الخطأ التالي عند تشغيل النص البرمجي:
عنوان البريد الإلكتروني غير صالح: john (السطر 5)
ما يجعل تحديد وحلّ هذه الأخطاء أكثر صعوبة هو أنّ البيانات التي يتم تمريرها إلى الدالة لا تكون مكتوبة في الرمز البرمجي في أغلب الأحيان، بل يتم سحب تلك البيانات من جدول بيانات أو نموذج أو مصدر بيانات خارجي آخر. يمكن أن يساعدك استخدام تقنيات تصحيح الأخطاء التالية في تحديد سبب هذه الأخطاء.
الأخطاء الشائعة
في ما يلي قائمة بالأخطاء الشائعة وأسبابها.
تمّ تفعيل الخدمة مرّات كثيرة جدًا: <اسم الإجراء>
يشير هذا الخطأ إلى أنك تجاوزت حصتك اليومية لإجراء معين. على سبيل المثال، قد يظهر لك هذا الخطأ إذا كنت ترسل عددًا كبيرًا جدًا من الرسائل الإلكترونية في يوم واحد. يتم تحديد الحصص على مستويات مختلفة لحسابات المستهلكين والنطاق والحسابات المميزة، وهي عرضة للتغيير في أي وقت دون إعلان مسبق من Google. يمكنك الاطّلاع على حدود الحصة لإجراءات مختلفة في مستندات حصة Apps Script.
الخادم غير متاح. أو حدث خطأ في الخادم، يُرجى إعادة المحاولة.
هناك بضعة أسباب محتملة لهذه الأخطاء:
- خادم أو نظام Google غير متاح مؤقتًا. انتظر بضع لحظات وجرب تشغيل النص البرمجي مرة أخرى.
- هناك خطأ في النص البرمجي لا يتضمّن رسالة خطأ مقابلة. جرِّب تصحيح أخطاء النص البرمجي ومعرفة ما إذا كان بإمكانك عزل المشكلة.
- هناك خطأ في "برمجة تطبيقات Google" يتسبب في حدوث هذا الخطأ. للحصول على تعليمات حول البحث عن تقارير الأخطاء وتقديمها، راجِع الأخطاء. قبل الإبلاغ عن خطأ جديد، يمكنك البحث لمعرفة ما إذا كان الآخرون قد أبلغوا عنه من قبل.
يجب الحصول على إذن لتنفيذ هذا الإجراء.
يشير هذا الخطأ إلى أنّ النص البرمجي لا يملك التفويض اللازم لتشغيله. عند تشغيل نص برمجي في "محرر النصوص البرمجية" أو من عنصر قائمة مخصّص، يتم عرض مربع حوار تفويض للمستخدم. ومع ذلك، عند تشغيل نص برمجي من عامل تشغيل أو تضمينه في صفحة على "مواقع Google" أو تشغيله كخدمة، لا يمكن عرض مربع الحوار ويظهر هذا الخطأ.
لتفويض النص البرمجي، افتح "أداة تعديل النصوص البرمجية" وشغِّل أي دالة. يظهر طلب التفويض حتى تتمكن من تفويض مشروع النص البرمجي. إذا كان النص البرمجي يحتوي على خدمات جديدة غير مصرَّح بها، عليك إعادة تفويض النص البرمجي.
يحدث هذا الخطأ غالبًا بسبب عوامل التشغيل التي يتم تفعيلها قبل أن يمنح المستخدم الإذن بها. إذا لم يكن بإمكانك الوصول إلى مشروع النص البرمجي (لأنّ الخطأ يحدث عند إضافة تستخدمها مثلاً)، يمكنك عادةً تفويض النص البرمجي باستخدام الإضافة مرة أخرى. إذا استمر تشغيل عامل تشغيل وتسبّب في ظهور هذا الخطأ، يمكنك إزالة عوامل التشغيل باتّباع الخطوات التالية:
- على يمين مشروع Apps Script، انقر على العوامل المشغِّلة .
- على يسار العامل المشغِّل الذي تريد إزالته، انقر على رمز المزيد > حذف العامل المشغِّل.
يمكنك أيضًا إزالة عوامل تشغيل الإضافات التي تتسبّب في حدوث مشاكل من خلال إلغاء تثبيت الإضافة.
Access denied: DriveApp أو أوقفت سياسة النطاق تطبيقات Drive التابعة لجهات خارجية
بإمكان مشرفي Google Workspace النطاقات إيقاف Drive API لنطاقاتهم، ما يمنع المستخدمين من تثبيت تطبيقات Google Drive واستخدامها. يمنع هذا الإعداد أيضًا المستخدمين من استخدام إضافات "برمجة تطبيقات Google" التي تستخدم خدمة Drive أو خدمة Drive المتقدّمة (حتى إذا تم السماح بالنص البرمجي قبل إيقاف المشرف لواجهة برمجة تطبيقات Drive).
إذا تم نشر إضافة أو تطبيق ويب يستخدم خدمة Drive للتثبيت على مستوى النطاق وتم تثبيته من قِبل المشرف لبعض المستخدمين أو جميعهم في النطاق، سيعمل النص البرمجي لهؤلاء المستخدمين حتى إذا كانت واجهة برمجة تطبيقات Drive غير مفعّلة في النطاق.
ليس لدى النص البرمجي إذن بالحصول على هوية المستخدم النشط.
يشير ذلك إلى أنّ هوية المستخدم النشط وبريده الإلكتروني غير متاحَين للملفّ الشخصي. ينتج هذا التحذير عن طلب برمجي إلى
Session.getActiveUser().
ويمكن أن يحدث ذلك أيضًا نتيجة طلب برمجي إلى
Session.getEffectiveUser()
إذا كان النص البرمجي قيد التشغيل في وضع تفويض غير
AuthMode.FULL.
في حال تمّ إرسال هذا التحذير، لن تعرض الطلبات اللاحقة التي يتم إرسالها إلى User.getEmail() سوى "".
هناك عدد من الطرق لتحديد المشاكل وحلّها في هذا التحذير، وذلك استنادًا إلى
وضع التفويض الذي يتم تشغيل النص البرمجي بموجبه. يتم عرض وضع التفويض
في الدوالّ المشغَّلة على أنّه سمة
authMode للمَعلمة e
مَعلمة الحدث.
- في
AuthMode.FULL، ننصحك باستخدامSession.getEffectiveUser()بدلاً من ذلك. - في
AuthMode.LIMITED، تأكَّد من أنّه منح المالك الإذن للنص البرمجي. - في أوضاع التفويض الأخرى، تجنَّب استدعاء أي من الطريقتين.
- إذا كنت من العملاء Google Workspace الذين ظهرت لهم مؤخرًا هذا التحذير من عامل تشغيل قابل للتثبيت، تأكَّد من أنّه يعمل كمستخدم داخل مؤسستك.
المكتبة غير متوفّرة
إذا أضفت مكتبة رائجة إلى النص البرمجي، قد تظهر لك رسالة خطأ تفيد بأنّها غير متوفّرة، على الرغم من أنّ المكتبة مُدرَجة كعنصر تابع للنص البرمجي. قد يكون السبب أن عددًا كبيرًا جدًا من الأشخاص يدخلون إلى المكتبة في نفس الوقت. لتجنُّب حدوث هذا الخطأ، جرِّب أحد الحلول التالية:
- انسخ رمز المكتبة والصقه في النص البرمجي وأزِل تبعية المكتبة.
- انسخ النص البرمجي للمكتبة وانشره كمكتبة من حسابك. احرص على تعديل الاعتماد في النص البرمجي الأصلي على المكتبة الجديدة بدلاً من المكتبة المتاحة للجميع.
حدث خطأ بسبب عدم توفّر إصدار مكتبة أو إصدار نشر. رمز الخطأ Not_Found
تشير رسالة الخطأ هذه إلى أحد ما يلي:
- تم حذف الإصدار المنشور من النص البرمجي. لتعديل الإصدار الذي تم نشره من النص البرمجي، اطّلِع على تعديل عملية نشر ذات إصدار.
- تم حذف إصدار المكتبة الذي يستخدمه النص البرمجي. لمعرفة مكتبة المحتوى التي لا تظهر، انقر على رمز
المزيد
> الفتح في علامة تبويب جديدة بجانب اسم المكتبة. تعطي المكتبة المفقودة
رسالة خطأ. بعد العثور على المكتبة التي تحتاج إلى تعديلها، اتّخِذ أحد الإجراءات التالية:
- عدِّل المكتبة لاستخدام إصدار مختلف. اطّلِع على تعديل مكتبة.
- أزِل المكتبة المحذوفة من مشروع النص البرمجي ورمزه. راجِع مقالة إزالة مكتبة.
- يتضمّن النص البرمجي للمكتبة التي يستخدمها النص البرمجي مكتبة
أخرى تستخدم إصدارًا تم حذفه. نفِّذ أحد الإجراءات التالية:
- إذا كان لديك إذن وصول للتعديل إلى المكتبة التي يستخدمها النص البرمجي، عدِّل المكتبة الثانوية في هذا النص البرمجي إلى إصدار حالي.
- عدِّل المكتبة لاستخدام إصدار مختلف. اطّلِع على تعديل مكتبة.
- أزِل المكتبة من مشروع النص البرمجي ورمزه. راجِع مقالة إزالة مكتبة.
الخطأ 400: invalid_scope عند استدعاء Google Chat API باستخدام الخدمة المتقدّمة
إذا ظهرت لك رسالة الخطأ Error 400: invalid_scope مع الرمزSome requested scopes cannot be shown،Some requested scopes cannot be shown يعني ذلك أنّك لم تحدِّد أي نطاقات تفويض في ملفappsscript.json لمشروع Apps Script. في معظم الحالات، تحدد أداة Apps Script تلقائيًا النطاقات التي يحتاجها النص البرمجي،
ولكن عند استخدام الخدمة المتقدّمة في Chat، عليك إضافة نطاقات التفويض التي يستخدمها النص البرمجي يدويًا إلىملف بيان
مشروع Apps Script. راجِع مقالة
ضبط نطاقات صريحة.
لحل هذا الخطأ، أضِف نطاقات التفويض المناسبة
إلى ملف appsscript.json في مشروع "برمجة تطبيقات Google" كجزء من
مصفوفة oauthScopes. على سبيل المثال، لاستدعاء الأسلوب
spaces.messages.create
، أضِف ما يلي:
"oauthScopes": [
"https://www.googleapis.com/auth/chat.messages.create"
]
لا يسمح المشرف في مؤسستك باستدعاءات UrlFetch لعنوان URL <URL>
يمكن لمشرفي Google Workspace تفعيل قائمة مسموح بها في وحدة تحكُّم المشرف للتحكّم في النطاقات الخارجية التي يمكنك الوصول إليها من خلال Apps Script.
لحلّ الخطأ، يُرجى التواصل مع المشرف لإضافة عنوان URL إلى القائمة المسموح بها.
تصحيح الأخطاء
لا تؤدي بعض الأخطاء إلى عرض رسالة خطأ. قد يكون هناك خطأ أكثر دقّة حيث تكون التعليمة البرمجية صحيحة من الناحية الفنية ويمكن تنفيذها، لكن النتائج لا تتوقعها. في ما يلي بعض الاستراتيجيات للتعامل مع هذه المواقف وإجراء المزيد من التحقيق في نص برمجي لا يعمل على النحو الذي تتوقعه.
التسجيل
أثناء تصحيح الأخطاء، من المفيد غالبًا تسجيل المعلومات أثناء تنفيذ مشروع نص برمجي. تتضمّن Google Apps Script طريقتَين لتسجيل المعلومات: خدمة تسجيل في السحابة الإلكترونية وخدمات وحدة التحكّم والسجلّ الأكثر بساطةً والمضمّنة في محرِّر Apps Script.
اطّلِع على دليل التسجيل للحصول على مزيد من التفاصيل.
Error Reporting
يتم تلقائيًا تسجيل الاستثناءات التي تحدث بسبب أخطاء وقت التشغيل باستخدام خدمة "الإبلاغ عن الأخطاء" في Google Cloud. تتيح لك هذه الخدمة البحث عن رسائل الاستثناءات وفلترتها التي ينشئها مشروع النص البرمجي.
للوصول إلى ميزة "الإبلاغ عن الأخطاء"، اطّلِع على مقالة عرض سجلات Cloud وتقارير الأخطاء في وحدة تحكّم Google Cloud Platform.
عمليات التنفيذ
في كل مرة تُشغِّل فيها نصًا برمجيًا، يُنشئ Apps Script سجلاً للتنفيذ، بما في ذلك سجلّات Cloud. يمكن أن تساعدك هذه السجلات في فهم الإجراءات التي نفّذها النص البرمجي.
لعرض عمليات تنفيذ النص البرمجي في مشروع Apps Script، انقر على عمليات التنفيذ على يمين الصفحة.
التحقّق من حالة خدمة Apps Script
على الرغم من ندرة حدوث ذلك، إلا أنّ بعض خدمات Google Workspace (مثل Gmail أو Drive) قد تواجه أحيانًا مشاكل مؤقتة يمكن أن تؤدي إلى انقطاع الخدمة. عند حدوث ذلك، قد لا تعمل مشاريع "برمجة تطبيقات Google" التي تتفاعل مع هذه الخدمات بالشكل المتوقع.
يمكنك التحقّق مما إذا كان هناك انقطاع في خدمة Google Workspace من خلال الاطّلاع على لوحة بيانات حالة Google Workspace. إذا كان هناك انقطاع في الخدمة حاليًا، يمكنك الانتظار إلى أن يتم حلّ المشكلة أو طلب مساعدة إضافية في مركز مساعدة Google Workspace أو مستندات المشاكل المعروفة في Google Workspace.
استخدام برنامج تصحيح الأخطاء ونقاط الإيقاف
لتحديد المشاكل في النص البرمجي، يمكنك تشغيله في وضع تصحيح الأخطاء. عند التشغيل في وضع تصحيح الأخطاء، يتم إيقاف النص البرمجي مؤقتًا عند الوصول إلى نقطة توقّف، وهي سطر تميّزه في النص البرمجي وتعتقد أنّه قد يتضمّن مشكلة. عندما يتم إيقاف نص برمجي مؤقتًا، يعرض قيمة كل متغيّر في تلك اللحظة، ما يتيح لك فحص الوظائف الداخلية للنص البرمجي بدون الحاجة إلى إضافة الكثير من عبارات التسجيل.
إضافة نقطة إيقاف
لإضافة نقطة توقف، مرِّر مؤشر الماوس فوق رقم سطر السطر الذي تريد إضافته. على يمين رقم السطر، انقر على الدائرة. تعرض الصورة أدناه مثالاً على نقطة توقّف تمت إضافتها إلى نص برمجي:
تشغيل نص برمجي في وضع تصحيح الأخطاء
لتشغيل النص البرمجي في وضع تصحيح الأخطاء، انقر على تصحيح الأخطاء في أعلى المحرِّر.
قبل أن يُشغِّل النص البرمجي السطر الذي يتضمّن نقطة التوقف، يتوقّف مؤقتًا ويعرض جدولاً لمعلومات تصحيح الأخطاء. يمكنك استخدام هذا الجدول لفحص بيانات مثل قيم المعلَمات والمعلومات المخزَّنة في العناصر.
للتحكّم في طريقة تنفيذ النص البرمجي، في أعلى لوحة "أداة تصحيح الأخطاء"، استخدِم الأزرار "الخطوة إلى الأمام" و"الخطوة إلى الأمام بدون تنفيذ" و"الخطوة إلى الوراء". تتيح لك هذه الأدوات تنفيذ ملف برمجي سطرًا واحدًا في كل مرة وفحص كيفية تغيُّر القيم بمرور الوقت.
مشاكل في حسابات Google المتعدّدة
إذا سجّلت الدخول إلى حسابات متعددة على Google في الوقت نفسه، قد تواجه مشكلة في الوصول إلى إضافاتك وتطبيقات الويب. لا يتوفر تسجيل الدخول المتعدد أو تسجيل الدخول إلى حسابات Google متعددة في الوقت نفسه لمشاريع برمجة التطبيقات أو الإضافات أو تطبيقات الويب.
إذا فتحت محرِّر "برمجة تطبيقات Google" أثناء تسجيل الدخول إلى أكثر من حساب واحد، ستطلب منك Google اختيار الحساب الذي تريد المتابعة باستخدامه.
إذا فتحت تطبيق ويب أو إضافة وواجهت مشاكل في تسجيل الدخول المتعدد، جرِّب أحد الحلول التالية:
- سجِّل الخروج من جميع حساباتك على Google وسجِّل الدخول فقط إلى الحساب الذي يحتوي على الإضافة أو تطبيق الويب الذي تريد الوصول إليه.
- افتح نافذة تصفُّح متخفّي في Google Chrome أو نافذة تصفُّح بخصوصيّة تامّة مماثلة، وسجِّل الدخول إلى حساب Google الذي يتضمّن الإضافة أو تطبيق الويب الذي تريد الوصول إليه.
الحصول على المساعدة
يمكن أن يؤدي تصحيح مشكلة ما باستخدام الأدوات والتقنيات المذكورة أعلاه إلى حل مجموعة متنوعة من المشكلات، ولكن قد تكون هناك مشكلات تواجهها وتتطلب مساعدة إضافية لحلها. يُرجى الاطّلاع على صفحة الدعم للحصول على معلومات عن مكان طرح الأسئلة والإبلاغ عن الأخطاء.