حتى أكثر المطوّرين خبرةً نادرًا ما يكتبون الرمز بشكل صحيح في المحاولة الأولى، ما يجعل تحديد المشاكل وحلّها جزءًا مهمًا من عملية التطوير. في هذا القسم، سنتناول بعض التقنيات التي يمكن أن تساعدك في العثور على الأخطاء في النصوص البرمجية وفهمها وتصحيحها.
رسائل الخطأ
عندما يواجه البرنامج النصي خطأً، يتم عرض رسالة خطأ. تتضمّن الرسالة رقم سطر يُستخدَم لتحديد المشاكل وحلّها. هناك نوعان أساسيان من الأخطاء يتم عرضها بهذه الطريقة: أخطاء البنية وأخطاء وقت التشغيل.
أخطاء البنية
تحدث أخطاء الصيغة بسبب كتابة رمز لا يتّبع قواعد JavaScript، ويتم رصد الأخطاء بمجرد محاولة حفظ النص البرمجي. على سبيل المثال، يحتوي مقتطف الرمز التالي على خطأ في الصيغة:
function emailDataRow(rowNumber) { var sheet = SpreadsheetApp.getActiveSheet(); var data = sheet.getDataRange().getValues(); var rowData = data[rowNumber-1].join(" "; MailApp.sendEmail('[email protected]', '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 Apps Script يتسبّب في حدوث هذا الخطأ. للحصول على تعليمات حول البحث عن تقارير الأخطاء وتقديمها، راجِع الأخطاء. قبل إرسال تقرير جديد عن خطأ، ابحث للتأكّد مما إذا كان مستخدمون آخرون قد أبلغوا عنه من قبل.
يجب الحصول على إذن لتنفيذ هذا الإجراء.
يشير هذا الخطأ إلى أنّ النص البرمجي لا يتضمّن الإذن اللازم لتشغيله. عند تشغيل نص برمجي في "محرّر النصوص البرمجية" أو من عنصر قائمة مخصّص، سيظهر مربّع حوار طلب الإذن للمستخدم. ومع ذلك، عند تشغيل نص برمجي من مشغّل أو تضمينه في صفحة "مواقع Google" أو تشغيله كخدمة، لا يمكن عرض مربّع الحوار ويظهر هذا الخطأ.
لتفويض النص البرمجي، افتح "محرّر النصوص البرمجية" وشغِّل أي دالة. سيظهر طلب الإذن حتى تتمكّن من منح الإذن لمشروع البرنامج النصي. إذا كان النص البرمجي يتضمّن خدمات جديدة غير مصرّح بها، عليك إعادة منح الإذن للنص البرمجي.
يحدث هذا الخطأ بشكل متكرّر بسبب مشغّلات يتم تفعيلها قبل أن يمنح المستخدم الإذن بذلك. إذا لم يكن لديك إذن الوصول إلى مشروع النص البرمجي (لأنّ الخطأ يحدث في إضافة تستخدمها، مثلاً)، يمكنك عادةً منح الإذن للنص البرمجي من خلال استخدام الإضافة مرة أخرى. إذا استمرّ المشغّل في العمل وتسبّب في حدوث هذا الخطأ، يمكنك إزالة المشغّلات باتّباع الخطوات التالية:
- على يمين مشروع Apps Script، انقر على المشغّلات .
- على يسار المشغّل الذي تريد إزالته، انقر على "المزيد" > "حذف المشغّل".
يمكنك أيضًا إزالة مشغّلات الإضافة التي تتسبّب في المشاكل من خلال إلغاء تثبيت الإضافة.
تم رفض الوصول: DriveApp أو أوقفت سياسة النطاق تطبيقات Drive التابعة لجهات خارجية
يمكن لمشرفي Google Workspace النطاقات إيقاف Google Workspace واجهة برمجة تطبيقات Drive لنطاقهم، ما يمنع المستخدمين من تثبيت تطبيقات Google Drive واستخدامها. يمنع هذا الإعداد أيضًا المستخدمين من استخدام إضافات "برمجة تطبيقات Google" التي تستخدم خدمة Drive أو خدمة Drive المتقدّمة (حتى إذا تم منح الإذن للنص البرمجي قبل أن يوقف المشرف واجهة برمجة التطبيقات Drive API).
ومع ذلك، إذا تم نشر إضافة أو تطبيق ويب يستخدم خدمة Drive من أجل التثبيت على مستوى النطاق وثبَّت المشرف الإضافة أو التطبيق لبعض المستخدمين أو جميعهم في النطاق، ستعمل وظائف البرنامج النصي لهؤلاء المستخدمين حتى إذا تم إيقاف Drive API في النطاق.
ليس لدى النص البرمجي إذن للحصول على هوية المستخدم النشط.
تشير إلى أنّ هوية المستخدم النشط وبريده الإلكتروني غير متاحَين للبرنامج النصي. ينتج هذا التحذير عن طلب إلى 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، يعني ذلك أنّك لم تحدّد أي نطاقات تفويض في ملف appsscript.json في مشروع Apps Script. في معظم الحالات، تحدّد خدمة Apps Script تلقائيًا النطاقات التي يحتاجها البرنامج النصي، ولكن عند استخدام خدمة Chat المتقدّمة، عليك إضافة نطاقات التفويض التي يستخدمها البرنامج النصي يدويًا إلى ملف البيان الخاص بمشروع Apps Script. راجِع مقالة ضبط النطاقات الواضحة.
لحلّ الخطأ، أضِف نطاقات الأذونات المناسبة إلى ملف appsscript.json في مشروع Apps Script كجزء من مصفوفة oauthScopes. على سبيل المثال، لاستدعاء الطريقة spaces.messages.create ، أضِف ما يلي:
"oauthScopes": [ "https://www.googleapis.com/auth/chat.messages.create" ] لا يسمح المشرف في مؤسستك باستدعاءات UrlFetch لـ <URL>
يمكن لمشرفي Google Workspace تفعيل قائمة السماح في "وحدة تحكّم المشرف" للتحكّم في النطاقات الخارجية التي يمكنك الوصول إليها من خلال Apps Script.
لحلّ الخطأ، عليك التواصل مع المشرف لطلب إضافة عنوان URL إلى قائمة العناوين المسموح بها.
تصحيح الأخطاء
لا تؤدي جميع الأخطاء إلى ظهور رسالة خطأ. قد يكون هناك خطأ أكثر دقة، حيث يكون الرمز البرمجي صحيحًا من الناحية الفنية ويمكن تنفيذه، ولكن النتائج ليست كما تتوقّع. في ما يلي بعض الاستراتيجيات للتعامل مع هذه الحالات وإجراء المزيد من التحقيقات بشأن نص برمجي لا يعمل بالطريقة التي تتوقّعها.
التسجيل
أثناء تصحيح الأخطاء، من المفيد غالبًا تسجيل المعلومات أثناء تنفيذ مشروع نص برمجي. تتضمّن Google Apps Script طريقتَين لتسجيل المعلومات: خدمة تسجيل الدخول إلى السحابة الإلكترونية وخدمات Logger وConsole الأساسية المضمّنة في محرّر Apps Script.
راجِع دليل التسجيل لمزيد من التفاصيل.
Error Reporting
يتم تلقائيًا تسجيل الاستثناءات التي تحدث بسبب أخطاء وقت التشغيل باستخدام خدمة "تقارير الأخطاء في Google Cloud". تتيح لك هذه الخدمة البحث عن رسائل الأخطاء التي ينشئها مشروع البرنامج النصي وفلترتها.
للوصول إلى "تقارير الأخطاء"، راجِع عرض سجلّات Cloud وتقارير الأخطاء في وحدة تحكّم Google Cloud Platform.
عمليات التنفيذ
في كل مرة تشغّل فيها نصًا برمجيًا، يسجّل Apps Script عملية التنفيذ، بما في ذلك سجلّات Cloud. يمكن أن تساعدك هذه السجلات في معرفة الإجراءات التي نفّذها النص البرمجي.
للاطّلاع على عمليات تنفيذ النص البرمجي في مشروع "برمجة تطبيقات Google"، انقر على عمليات التنفيذ في الجانب الأيمن.
التحقّق من حالة خدمة "برمجة التطبيقات"
على الرغم من أنّ هذا الخطأ نادرًا ما يحدث، ولكن قد تواجه بعض خدمات Google Workspace (مثل Gmail أو Drive) مشاكل مؤقتة تؤدي إلى انقطاع الخدمة. عند حدوث ذلك، قد لا تعمل مشاريع "برمجة التطبيقات" التي تتفاعل مع هذه الخدمات على النحو المتوقّع.
يمكنك التحقّق مما إذا كان هناك انقطاع في خدمة Google Workspace من خلال الاطّلاع على لوحة بيانات حالة Google Workspace. في حال حدوث انقطاع حاليًا، يمكنك الانتظار إلى أن يتم حلّه أو طلب مساعدة إضافية من خلال مركز مساعدة Google Workspace أو مستند المشاكل المعروفة في Google Workspace.
استخدام أداة تصحيح الأخطاء ونقاط التوقّف
لتحديد المشاكل في النص البرمجي، يمكنك تشغيله في وضع تصحيح الأخطاء. عند تشغيل نص برمجي في وضع التصحيح، يتوقف النص البرمجي مؤقتًا عند الوصول إلى نقطة توقّف، وهي سطر تم تمييزه في النص البرمجي وتعتقد أنّه قد يتضمّن مشكلة. عندما يتم إيقاف نص برمجي مؤقتًا، يتم عرض قيمة كل متغيّر في تلك اللحظة، ما يتيح لك فحص طريقة عمل النص البرمجي بدون الحاجة إلى إضافة الكثير من عبارات التسجيل.
إضافة نقطة توقّف
لإضافة نقطة توقّف، مرِّر مؤشر الماوس فوق رقم السطر الذي تريد إضافة نقطة التوقّف إليه. على يمين رقم السطر، انقر على الدائرة. تعرض الصورة أدناه مثالاً على نقطة توقّف تمت إضافتها إلى نص برمجي:
تشغيل نص برمجي في وضع تصحيح الأخطاء
لتشغيل النص البرمجي في وضع تصحيح الأخطاء، انقر على تصحيح الأخطاء في أعلى المحرّر.
قبل أن ينفّذ النص البرمجي السطر الذي يتضمّن نقطة توقّف، يتوقّف مؤقتًا ويعرض جدولاً يتضمّن معلومات تصحيح الأخطاء. يمكنك استخدام هذا الجدول لفحص البيانات، مثل قيم المَعلمات والمعلومات المخزّنة في العناصر.
للتحكّم في طريقة تنفيذ البرنامج النصي، استخدِم الأزرار "التنفيذ خطوة بخطوة" و"التنفيذ مع تخطّي الاستدعاء" و"التنفيذ حتى الخروج" في أعلى لوحة "أداة تصحيح الأخطاء". تتيح لك هذه الأدوات تشغيل البرنامج النصي سطرًا واحدًا في كل مرة وفحص كيفية تغيُّر القيم بمرور الوقت.
خطأ: لا يتوفّر رمز المصدر للسطر الحالي
يظهر هذا الخطأ عندما لا يتوفّر ملف تصحيح أخطاء نشط. لا تتيح "برمجة تطبيقات Google" عرض النصوص البرمجية التي يتم إنشاؤها ديناميكيًا بلغة JavaScript (JS) في محرّر النصوص البرمجية، مثل تلك التي يتم إنشاؤها باستخدام eval() وnew Function(). يتم إنشاء هذه النصوص البرمجية وتنفيذها ضمن محرك V8، ولكن لا يتم تمثيلها كملفات مستقلة في المحرر. إذا نفّذت هذه البرامج النصية خطوة بخطوة، سيظهر لك هذا الخطأ.
على سبيل المثال، ضع الرمز التالي في اعتبارك:
function myFunction() { eval('a=2'); } عند استدعاء eval()، يتم التعامل مع وسيطته على أنّها رمز JS ويتم تشغيلها كنص برمجي تم إنشاؤه ديناميكيًا داخل محرّك V8. يظهر هذا الخطأ عند استخدام ميزة eval(). إذا كان النص البرمجي يتضمّن تعليقًا //# sourceURL، سيظهر اسمه في حزمة استدعاء الدوال البرمجية. بخلاف ذلك، يظهر كإدخال بدون اسم.
على الرغم من ظهور رسالة الخطأ، تظل جلسة تصحيح الأخطاء نشطة ويمكن مواصلة التنفيذ. للمتابعة، انتقِل إلى الخطوة التالية أو الخطوة السابقة أو استأنِف التنفيذ. ومع ذلك، سيستمر ظهور هذا الخطأ طالما أنّ التنفيذ يظل ضمن نطاق النص البرمجي الديناميكي. بعد أن ينتقل التنفيذ خارج النص البرمجي الديناميكي، يستمر تصحيح الأخطاء بدون هذا الخطأ.
مشاكل في حسابات Google المتعددة
إذا سجّلت الدخول إلى حسابات متعددة على Google في الوقت نفسه، قد تواجه مشاكل في الوصول إلى الإضافات وتطبيقات الويب. لا يتوفر تسجيل الدخول المتعدد أو تسجيل الدخول إلى حسابات Google متعددة في الوقت نفسه لمشاريع برمجة التطبيقات أو الإضافات أو تطبيقات الويب.
إذا فتحت محرّر "برمجة تطبيقات Google" أثناء تسجيل الدخول إلى أكثر من حساب واحد، سيطلب منك Google اختيار الحساب الذي تريد المتابعة باستخدامه.
إذا فتحت تطبيق ويب أو إضافة وواجهت مشاكل في تسجيل الدخول المتعدد، جرِّب أحد الحلول التالية:
- سجِّل الخروج من جميع حساباتك على Google وسجِّل الدخول إلى الحساب الذي يحتوي على الإضافة أو تطبيق الويب الذي تريد الوصول إليه فقط.
- افتح نافذة للتصفُّح المتخفي في Google Chrome أو نافذة تصفُّح بخصوصيّة تامّة، وسجِّل الدخول إلى حساب Google الذي يتضمّن الإضافة أو تطبيق الويب الذي تريد الوصول إليه.
الحصول على المساعدة
يمكن أن يؤدي تصحيح الأخطاء في مشكلة باستخدام الأدوات والأساليب المذكورة أعلاه إلى حل مجموعة متنوعة من المشاكل، ولكن قد تواجه مشاكل تتطلب بعض المساعدة الإضافية لحلها. يُرجى الاطّلاع على صفحة الدعم للحصول على معلومات حول الأماكن التي يمكنك فيها طرح الأسئلة والإبلاغ عن الأخطاء.