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

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

رسائل الخطأ

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

أخطاء في البنية

تحدث أخطاء البنية بسبب كتابة رمز لا يتّبع قواعد نحو 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" أو تشغيله كخدمة، لا يمكن عرض مربع الحوار ويظهر هذا الخطأ.

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

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

  1. على يمين مشروع Apps Script، انقر على العوامل المشغِّلة .
  2. على يسار العامل المشغِّل الذي تريد إزالته، انقر على رمز المزيد > حذف العامل المشغِّل.

يمكنك أيضًا إزالة عوامل تشغيل الإضافات التي تتسبّب في حدوث مشاكل من خلال إلغاء تثبيت الإضافة.

Access denied: DriveApp أو أوقفت سياسة النطاق تطبيقات Drive التابعة لجهات خارجية

يمكن لمشرفي Google Workspace النطاقات إيقاف Drive API لنطاقاتهم، ما يمنع المستخدمين من تثبيت تطبيقات 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‏ <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 متعددة في الوقت نفسه لمشاريع برمجة التطبيقات أو الإضافات أو تطبيقات الويب.

  • إذا فتحت محرِّر Apps Script وأنت مسجِّل الدخول إلى أكثر من حساب واحد، سيطلب منك Google اختيار الحساب الذي تريد المتابعة باستخدامه.

  • إذا فتحت تطبيق ويب أو إضافة وواجهت مشاكل في تسجيل الدخول المتعدد، جرِّب أحد الحلول التالية:

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

الحصول على المساعدة

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