Penanganan error dan pesan untuk Konektor Komunitas

Untuk memberikan pengalaman pengguna yang baik, kode Anda harus menangani error dengan benar. Memberi pengguna pesan error yang dapat ditindaklanjuti, yang menjelaskan langkah-langkah korektif untuk menyelesaikan masalah.

Dokumen ini menjelaskan error yang dapat terjadi pada konektor, cara kerja pesan error, dan cara menangani error konektor dengan benar.

Info: Untuk mempelajari lebih lanjut cara menangani pengecualian di JavaScript, lihat pernyataan try...catch.

Jenis error

Jenis dan penyebab error yang mungkin dialami pengguna saat menggunakan konektor Anda biasanya termasuk dalam salah satu dari tiga kategori berikut:

1. error internal konektor
2. error eksternal konektor
3. Error Looker Studio

Error internal dan eksternal konektor harus ditangani oleh developer konektor. Error ini terjadi karena kode yang ditulis developer.

Error internal konektor

Error internal konektor terjadi selama eksekusi konektor. Misalnya, jika konektor tidak dapat mengurai respons API selama eksekusi getData(). Error ini harus diantisipasi dan ditangani dengan penjelasan yang mudah digunakan jika berlaku.

Untuk informasi lebih lanjut tentang penanganan error internal konektor, lihat Praktik terbaik untuk menangani error konektor.

Error eksternal konektor

Error eksternal konektor terjadi setelah eksekusi konektor. Misalnya, saat permintaan getData() untuk tiga kolom hanya menampilkan data untuk dua kolom. Meskipun konektor telah menyelesaikan eksekusi, hal ini tidak memenuhi permintaan dari Looker Studio. Pengujian yang menyeluruh dapat mencegah error ini.

Error eksternal konektor biasanya dapat diperbaiki dengan meninjau detail error (jika tersedia) dan men-debug kode untuk mengidentifikasi masalah. Untuk mengetahui informasi selengkapnya tentang proses debug konektor, lihat Mendebug kode.

Error Looker Studio

Error Looker Studio adalah error yang tidak terkait dengan kode konektor Anda. Misalnya, jika pengguna mencoba menggunakan diagram deret waktu dengan sumber data tanpa dimensi tanggal/waktu.

Jika error tersebut tidak terkait langsung dengan konektor, maka tidak ada tindakan yang perlu dilakukan oleh developer konektor. Pengguna dapat menemukan bantuan tambahan dengan mengunjungi Pusat Bantuan Looker Studio.

Menampilkan pesan error

Menampilkan detail error berdasarkan status admin

Saat konektor menampilkan error, Looker Studio akan menampilkan pesan error, bergantung pada status admin pengguna.

• Jika pengguna adalah pengguna admin, dia akan melihat semua detailnya. Informasi ini mencakup pesan error, jenis error, dan pelacakan tumpukan.
• Jika pengguna bukan pengguna admin, dia hanya akan melihat detail jika error menyertakan pesan yang mudah digunakan. Untuk mempelajari lebih lanjut cara menampilkan pesan error kepada pengguna non-admin, lihat Menampilkan error yang ditampilkan kepada pengguna.

Poin Penting: Terapkan isAdminUser() untuk mengidentifikasi admin sehingga tingkat detail yang tepat ditampilkan kepada pengguna konektor.

Menampilkan error yang ditampilkan kepada pengguna

Secara default, hanya admin konektor yang dapat melihat detail error. Hal ini membantu mencegah pengungkapan informasi sensitif secara tidak sengaja, seperti kunci API dalam pelacakan tumpukan. Untuk menampilkan pesan error kepada pengguna non-admin, gunakan newUserError() dari layanan Apps Script Looker Studio.

Contoh:

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();

}

Dalam contoh ini, setText() menetapkan teks yang akan ditampilkan kepada semua pengguna, sedangkan setDebugText() menetapkan teks yang hanya akan ditampilkan kepada pengguna admin.

Praktik terbaik untuk menangani error konektor

Anda harus mencoba menangkap dan menangani error sebanyak mungkin selama eksekusi kode konektor Anda. Misalnya, beberapa operasi umum yang dapat menyebabkan error atau status yang tidak diinginkan meliputi:

• Upaya pengambilan URL yang gagal (error sementara, waktu tunggu)
• Tidak ada data yang tersedia untuk jangka waktu yang diminta
• Data dari API tidak dapat diurai atau diformat
• Token otorisasi telah dicabut

Menangani error yang dapat dipulihkan

Titik eksekusi konektor yang dapat gagal tetapi dapat dipulihkan harus ditangani. Misalnya, jika permintaan API gagal karena alasan non-fatal (misalnya, penghapusan beban server), permintaan API tersebut harus dicoba lagi sebelum menampilkan error.

Menangkap dan menampilkan error

Error yang tidak dapat dipulihkan harus ditangkap dan ditampilkan kembali. Kesalahan yang ditampilkan ulang akan membantu pengguna memahami mengapa kesalahan terjadi. Jika masalah dapat diperbaiki, detail tentang tindakan perbaikan harus diberikan.

Lihat menampilkan error yang ditampilkan kepada pengguna.

Mencatat error ke dalam log ke Stackdriver

Gunakan Stackdriver untuk logging error dan pesan lainnya. Langkah ini membantu Anda memahami error, men-debug masalah, dan menemukan pengecualian yang tidak tertangani.

Untuk mempelajari lebih lanjut tentang Stackdriver Error Reporting, cara mengaktifkan logging pengecualian untuk skrip, dan cara mengidentifikasi pengguna secara aman untuk tujuan proses debug, lihat Menggunakan Stackdriver Logging.

TIDAK DIGUNAKAN LAGI: Gunakan awalan DS_USER: untuk pesan error yang aman

Perhatian: Fungsi ini tidak digunakan lagi dan akan dihapus Juni 2019. Migrasikan ke newUserError(). Lihat menampilkan error yang ditampilkan kepada pengguna.

Untuk memberikan pesan error yang mudah digunakan kepada pengguna non-admin, sertakan awalan DS_USER: dengan pesan error. Awalan ini digunakan untuk mengidentifikasi pesan yang aman bagi pengguna non-admin dan tidak disertakan dalam pesan error yang sebenarnya.

Contoh berikut mencakup kasus saat pesan error akan ditampilkan kepada pengguna non-admin, sedangkan pesan error hanya akan ditampilkan kepada pengguna admin:

data-studio/errors.gs

Lihat di 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');
}

Catatan: Awalan DS_USER: hanya mengidentifikasi pesan aman bagi pengguna non-admin. Awalan ini tidak disertakan dalam pesan error sebenarnya yang ditampilkan kepada pengguna.