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

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

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

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

انواع خطاها

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

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

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

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

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

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

خطای خارجی رابط

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

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

خطای Looker Studio

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

اگر خطا مستقیماً به کانکتور مربوط نباشد، هیچ اقدامی برای توسعه دهنده کانکتور وجود ندارد. کاربران می توانند با مراجعه به مرکز راهنمای 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 Logging مراجعه کنید.

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

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

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

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