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

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

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

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

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

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

ข้อผิดพลาดภายในของตัวเชื่อมต่อ
ข้อผิดพลาดภายนอกของตัวเชื่อมต่อ
ข้อผิดพลาดของ 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

ดูใน GitHub

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");
  }
}