مدیریت خطا و پیام‌ها برای اتصال‌دهنده‌های انجمن

برای ارائه یک تجربه کاربری خوب، کد شما باید خطاها را به درستی مدیریت کند. پیام‌های خطای قابل پیگیری را به کاربران ارائه دهید که مراحل اصلاحی برای حل مشکل را شرح می‌دهند.

این سند خطاهایی را که ممکن است برای کانکتورها رخ دهد، نحوه عملکرد پیام‌های خطا و نحوه مدیریت صحیح خطاهای کانکتور را شرح می‌دهد.

اطلاعات: برای کسب اطلاعات بیشتر در مورد مدیریت استثنائات در جاوا اسکریپت، به دستور try...catch مراجعه کنید.

انواع خطاها

انواع و علل خطاهایی که کاربر ممکن است هنگام استفاده از کانکتور شما با آنها مواجه شود، معمولاً در یکی از سه دسته زیر قرار می‌گیرند:

  1. خطاهای داخلی کانکتور
  2. خطاهای خارجی کانکتور
  3. خطاهای استودیوی Looker

خطاهای داخلی و خارجی کانکتور باید توسط توسعه‌دهنده کانکتور مدیریت شوند. این خطاها به دلیل کد نوشته شده توسط توسعه‌دهنده رخ می‌دهند.

خطای داخلی کانکتور

خطاهای داخلی کانکتور در حین اجرای کانکتور رخ می‌دهند. برای مثال، اگر یک کانکتور نتواند پاسخ API را در حین اجرای getData() تجزیه کند. این خطاها باید پیش‌بینی شده و در صورت لزوم با توضیحات کاربرپسند مدیریت شوند.

برای اطلاعات بیشتر در مورد مدیریت خطاهای داخلی کانکتور، به بهترین شیوه‌ها برای مدیریت خطاهای کانکتور مراجعه کنید.

خطای خارجی کانکتور

خطاهای خارجی کانکتور پس از اجرای کانکتور رخ می‌دهند. برای مثال، هنگامی که یک درخواست getData() برای سه فیلد، فقط داده‌های دو فیلد را برمی‌گرداند. اگرچه کانکتور اجرا را کامل کرده است، اما درخواست Looker Studio را برآورده نکرده است. آزمایش دقیق می‌تواند از این خطاها جلوگیری کند.

خطاهای خارجی کانکتور معمولاً با بررسی جزئیات خطا (در صورت وجود) و اشکال‌زدایی کد برای شناسایی مشکل قابل رفع هستند. برای اطلاعات بیشتر در مورد اشکال‌زدایی کانکتور خود، به بخش اشکال‌زدایی کد خود مراجعه کنید.

خطای استودیوی Looker

خطاهای Looker Studio خطاهایی هستند که به کد کانکتور شما ربطی ندارند. برای مثال، اگر کاربری سعی کند از یک نمودار سری زمانی با منبع داده‌ای بدون بُعد تاریخ/زمان استفاده کند.

اگر خطا مستقیماً به کانکتور مربوط نباشد، هیچ اقدامی برای توسعه‌دهنده کانکتور وجود ندارد. کاربران می‌توانند با مراجعه به [مرکز راهنمایی Looker Studio] کمک بیشتری دریافت کنند.

نمایش پیام‌های خطا

نمایش جزئیات خطا بر اساس وضعیت ادمین

وقتی یک کانکتور خطایی ایجاد می‌کند، Looker Studio بسته به وضعیت ادمین کاربر، پیام خطا را نشان می‌دهد.

  • اگر کاربر مدیر باشد، تمام جزئیات را مشاهده خواهد کرد. این شامل پیام خطا، نوع خطا و ردیابی پشته می‌شود.
  • اگر کاربر مدیر نباشد ، فقط در صورتی جزئیات را مشاهده خواهد کرد که خطا شامل یک پیام کاربرپسند باشد. برای کسب اطلاعات بیشتر در مورد نمایش پیام‌های خطا به کاربران غیر مدیر، به بخش «نمایش خطاهای کاربر در مواجهه با خطاها» مراجعه کنید.

نمایش خطاهای کاربر

به طور پیش‌فرض، فقط مدیران رابط جزئیات خطا را می‌بینند. این به جلوگیری از افشای ناخواسته اطلاعات حساس، مانند کلید API در ردیابی پشته، کمک می‌کند. برای نمایش پیام‌های خطا به کاربران غیر مدیر، از 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 (خطاهای گذرا، وقفه‌های زمانی)
  • هیچ داده‌ای برای بازه زمانی درخواستی موجود نیست
  • داده‌های API قابل تجزیه یا قالب‌بندی نیستند
  • توکن‌های مجوز لغو شده‌اند

مدیریت خطاهای قابل بازیابی

نقاطی از اجرای کانکتور که ممکن است با شکست مواجه شوند اما قابل بازیابی هستند باید مدیریت شوند. برای مثال، اگر یک درخواست API به دلیل غیرمهلکی (مثلاً کاهش بار سرور) با شکست مواجه شود، باید قبل از بروز خطا دوباره امتحان شود.

گرفتن و پرتاب کردن خطاها

خطاهای غیرقابل بازیابی باید گرفته شده و دوباره ارسال شوند. خطای ارسال مجدد باید به کاربران کمک کند تا دلیل وقوع خطا را درک کنند. اگر مشکل قابل رفع است، جزئیات مربوط به اقدام اصلاحی باید ارائه شود.

ببینید کاربر با چه خطاهایی مواجه می‌شود .

ثبت خطاها در Stackdriver

از Stackdriver برای ثبت خطاها و سایر پیام‌ها استفاده کنید. این به درک خطاها، اشکال‌زدایی مشکلات و کشف استثنائات مدیریت نشده کمک می‌کند.

برای کسب اطلاعات بیشتر در مورد گزارش خطای Stackdriver، نحوه فعال کردن ثبت استثنا برای یک اسکریپت و نحوه شناسایی ایمن کاربران برای اهداف اشکال‌زدایی، به بخش «استفاده از ثبت Stackdriver» مراجعه کنید.

منسوخ شده: از پیشوند DS_USER: برای پیام‌های خطای ایمن استفاده کنید

برای ارائه پیام‌های خطای کاربرپسند به کاربران غیر مدیر، پیشوند DS_USER: را به پیام‌های خطا اضافه کنید. این پیشوند برای شناسایی پیام‌های ایمن برای کاربران غیر مدیر استفاده می‌شود و در پیام خطای واقعی گنجانده نشده است.

مثال‌های زیر شامل مواردی است که یک پیام خطا به کاربران غیر مدیر نمایش داده می‌شود و دیگری مواردی که یک پیام خطا فقط به کاربران مدیر نمایش داده می‌شود:

data-studio/errors.gs
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");
  }
}