تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

أخطاء داخلية في الموصّل
أخطاء خارجية في الموصل
أخطاء Looker Studio

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

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

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

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

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

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

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

خطأ في Looker Studio

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

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

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

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

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

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

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

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

مثال:

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

// Admin and non-admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('DS_USER:This will be shown to admin & non-admin.');
}

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