خطأ في المعالجة والرسائل الخاصة بـ "موصِّلات المنتدى"

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

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

ملاحظة: لمزيد من المعلومات حول التعامل مع الاستثناءات في JavaScript، يمكنك الاطّلاع على عبارة try...catch.

أنواع الأخطاء

تندرج أنواع الأخطاء وأسبابها التي قد يواجهها المستخدم عند استخدام الموصل عادةً في إحدى الفئات الثلاث التالية:

أخطاء داخلية في أداة الربط
أخطاء خارجية في أداة الربط
[أخطاء في "مركز البيانات"]

يجب أن يتعامل مطوّر الموصّل مع الأخطاء الداخلية والخارجية للموصّل. تحدث هذه الأخطاء بسبب الرمز الذي كتبه المطوِّر.

خطأ داخلي في الموصِّل

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

لمزيد من المعلومات حول معالجة الأخطاء الداخلية في الموصل، راجِع أفضل الممارسات لمعالجة أخطاء الموصل.

خطأ خارجي في الموصل

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

يمكن عادةً إصلاح الأخطاء الخارجية في أداة الربط من خلال مراجعة تفاصيل الخطأ (إذا كانت متاحة) وتصحيح أخطاء الرمز لتحديد المشكلة. لمزيد من المعلومات حول تصحيح أخطاء الموصل، يُرجى الاطّلاع على تصحيح أخطاء الرمز.

خطأ في "مركز البيانات"

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

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

عرض رسائل الخطأ

عرض تفاصيل الخطأ استنادًا إلى حالة المشرف

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

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

عرض أخطاء للمستخدمين

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

مثال:

try {
  // API request that can be malformed.
  getDataFromAPI();
} catch (e) {
  DataStudioApp.createCommunityConnector()
      .newUserError()
      .setDebugText('Error fetching data from API. Exception details: ' + e)
      .setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
      .throwException();

}

في هذا المثال، يضبط setText() النص الذي سيظهر لجميع المستخدمين، بينما يضبط setDebugText() النص الذي سيظهر للمستخدمين المشرفين فقط.

أفضل الممارسات للتعامل مع أخطاء الموصل

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

محاولة غير ناجحة لجلب عنوان URL (أخطاء مؤقتة، مهلات)
لا تتوفّر بيانات للفترة الزمنية المطلوبة
تعذّر تحليل البيانات أو تنسيقها من واجهة برمجة التطبيقات
تم إبطال رموز التفويض

التعامل مع الأخطاء القابلة للإصلاح

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

التقاط الأخطاء وطرحها

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

اطّلِع على عرض أخطاء للمستخدمين.

تسجيل الأخطاء في Stackdriver

استخدِم Stackdriver لتسجيل الأخطاء والرسائل الأخرى. يساعد ذلك في فهم الأخطاء وتصحيح المشاكل واكتشاف الاستثناءات التي لم تتم معالجتها.

لمزيد من المعلومات حول خدمة "الإبلاغ عن الأخطاء في Stackdriver" وكيفية تفعيل تسجيل الاستثناءات لنص برمجي وكيفية تحديد المستخدمين بأمان لأغراض تصحيح الأخطاء، يُرجى الاطّلاع على استخدام Stackdriver Logging.

تم الإيقاف نهائيًا: استخدِم البادئة `DS_USER:` لرسائل الخطأ الآمنة

لتوفير رسائل خطأ سهلة الاستخدام للمستخدمين غير المشرفين، أدرِج البادئة DS_USER: مع رسائل الخطأ. يُستخدم هذا البادئة لتحديد الرسائل الآمنة للمستخدمين من غير المشرفين، ولا يتم تضمينها في رسالة الخطأ الفعلية.

تتضمّن الأمثلة التالية حالة ستظهر فيها رسالة خطأ للمستخدمين غير المشرفين، وحالة أخرى ستظهر فيها رسالة خطأ للمستخدمين المشرفين فقط:

data-studio/errors.gs

عرض على GitHub

function showErrorToAllUsers() {
  try {
    // Code that might fail.
    throw new Error("Something went wrong");
  } catch (e) {
    throw new Error("DS_USER:This will be shown to admin & non-admin.");
  }
}

function showErrorToAdminUsers() {
  // Only admin users will see the following error.
  try {
    // Code that might fail.
    throw new Error("Something went wrong");
  } catch (e) {
    throw new Error("This message will only be shown to admin users");
  }
}