تمت ترجمة هذه الصفحة بواسطة 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');
}