การจัดการข้อผิดพลาดและข้อความสำหรับปลั๊กอินจากชุมชนสำหรับใช้ลิงก์ข้อมูล

โค้ดของคุณควรจัดการข้อผิดพลาดอย่างถูกต้องเพื่อมอบประสบการณ์การใช้งานที่ดีแก่ผู้ใช้ แสดงข้อความแสดงข้อผิดพลาดที่ดำเนินการได้แก่ผู้ใช้ ซึ่งจะระบุขั้นตอนการแก้ไขเพื่อ แก้ปัญหา

เอกสารนี้อธิบายข้อผิดพลาดที่อาจเกิดขึ้นกับตัวเชื่อมต่อ วิธีการทำงานของข้อความแสดงข้อผิดพลาด และวิธีจัดการข้อผิดพลาดของตัวเชื่อมต่ออย่างถูกต้อง

ข้อมูล: ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการข้อยกเว้นใน JavaScript ได้ที่คำสั่ง try...catch

ประเภทของข้อผิดพลาด

ประเภทและสาเหตุของข้อผิดพลาดที่ผู้ใช้อาจพบเมื่อใช้ตัวเชื่อมต่อ มักจะอยู่ใน 1 ใน 3 หมวดหมู่ต่อไปนี้

  1. ข้อผิดพลาดภายในของตัวเชื่อมต่อ
  2. ข้อผิดพลาดภายนอกของตัวเชื่อมต่อ
  3. ข้อผิดพลาดของ Looker Studio

ข้อผิดพลาดภายในและภายนอกของตัวเชื่อมต่อควรได้รับการจัดการโดยนักพัฒนาซอฟต์แวร์ตัวเชื่อมต่อ ข้อผิดพลาดเหล่านี้เกิดขึ้นเนื่องจากโค้ดที่นักพัฒนาแอปเขียนขึ้น

ข้อผิดพลาดภายในของเครื่องมือเชื่อมต่อ

ข้อผิดพลาดภายในของเครื่องมือเชื่อมต่อจะเกิดขึ้นระหว่างการดำเนินการเครื่องมือเชื่อมต่อ เช่น หากตัวเชื่อมต่อแยกวิเคราะห์การตอบกลับ API ไม่ได้ในระหว่างการดำเนินการของ getData() คุณควรคาดการณ์ข้อผิดพลาดเหล่านี้และจัดการด้วยคำอธิบายที่ใช้งานง่าย ในกรณีที่เกี่ยวข้อง

ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการข้อผิดพลาดภายในของตัวเชื่อมต่อได้ที่ แนวทางปฏิบัติแนะนำในการจัดการข้อผิดพลาดของตัวเชื่อมต่อ

ข้อผิดพลาดภายนอกของตัวเชื่อมต่อ

ข้อผิดพลาดภายนอกของเครื่องมือเชื่อมต่อจะเกิดขึ้นหลังจากการดำเนินการของเครื่องมือเชื่อมต่อ เช่น เมื่อgetData()คำขอสำหรับ 3 ฟิลด์แสดงผลข้อมูลเพียง 2 ฟิลด์ แม้ว่าตัวเชื่อมต่อจะดำเนินการเสร็จสมบูรณ์แล้ว แต่ก็ไม่เป็นไปตามคำขอจาก Looker Studio การทดสอบอย่างละเอียดจะช่วยป้องกันข้อผิดพลาดเหล่านี้ได้

โดยปกติแล้ว ข้อผิดพลาดภายนอกของตัวเชื่อมต่อจะแก้ไขได้โดยการตรวจสอบรายละเอียดข้อผิดพลาด (หากมี) และการแก้ไขข้อบกพร่องของโค้ดเพื่อระบุปัญหา ดูข้อมูลเพิ่มเติมเกี่ยวกับการ แก้ไขข้อบกพร่องของตัวเชื่อมต่อได้ที่แก้ไขข้อบกพร่องของโค้ด

ข้อผิดพลาดของ Looker Studio

ข้อผิดพลาดของ Looker Studio คือข้อผิดพลาดที่ไม่เกี่ยวข้องกับโค้ดเครื่องมือเชื่อมต่อ เช่น หากผู้ใช้พยายามใช้แผนภูมิอนุกรมเวลาที่มีแหล่งข้อมูลที่ไม่มี มิติข้อมูลวันที่/เวลา

หากข้อผิดพลาดไม่เกี่ยวข้องกับตัวเชื่อมต่อโดยตรง นักพัฒนาตัวเชื่อมต่อก็ไม่ต้องดำเนินการใดๆ ผู้ใช้สามารถดูความช่วยเหลือเพิ่มเติมได้โดยไปที่ศูนย์ช่วยเหลือของ Looker Studio

การแสดงข้อความแสดงข้อผิดพลาด

แสดงรายละเอียดข้อผิดพลาดตามสถานะผู้ดูแลระบบ

เมื่อตัวเชื่อมต่อแสดงข้อผิดพลาด Looker Studio จะแสดงข้อความแสดงข้อผิดพลาด โดยขึ้นอยู่กับสถานะผู้ดูแลระบบของผู้ใช้

  • หากผู้ใช้เป็นผู้ใช้ที่เป็นผู้ดูแลระบบ ผู้ใช้จะเห็นรายละเอียดทั้งหมด ซึ่งรวมถึง ข้อความแสดงข้อผิดพลาด ประเภทข้อผิดพลาด และสแต็กเทรซ
  • หากผู้ใช้ไม่ใช่ผู้ดูแลระบบ ผู้ใช้จะเห็นรายละเอียดก็ต่อเมื่อข้อผิดพลาดมีข้อความที่เข้าใจง่าย ดูข้อมูลเพิ่มเติมเกี่ยวกับการแสดงข้อความแสดงข้อผิดพลาดต่อผู้ใช้ที่ไม่ใช่ผู้ดูแลระบบได้ที่การแสดงข้อผิดพลาดต่อผู้ใช้

แสดงข้อผิดพลาดต่อผู้ใช้

โดยค่าเริ่มต้น มีเพียงผู้ดูแลระบบตัวเชื่อมต่อเท่านั้นที่จะเห็นรายละเอียดข้อผิดพลาด ซึ่งจะช่วยป้องกันไม่ให้มีการเปิดเผยข้อมูลที่ละเอียดอ่อนโดยไม่ได้ตั้งใจ เช่น คีย์ API ใน Stack Trace หากต้องการแสดงข้อความแสดงข้อผิดพลาดต่อผู้ใช้ที่ไม่ใช่ผู้ดูแลระบบ ให้ใช้ newUserError() จาก บริการ Apps Script ของ Looker Studio

ตัวอย่าง

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 Error Reporting วิธีเปิดใช้การบันทึกข้อยกเว้น สำหรับสคริปต์ และวิธีระบุผู้ใช้เพื่อการแก้ไขข้อบกพร่องอย่างปลอดภัยได้ที่การใช้ 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');
}