Penanganan error dan pesan untuk Konektor Komunitas

Untuk memberikan pengalaman pengguna yang baik, kode Anda harus menangani error dengan benar. Menyajikan pesan {i>error<i} yang dapat ditindaklanjuti kepada pengguna yang menguraikan langkah-langkah korektif untuk menyelesaikan masalah.

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

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

Jenis-jenis error

Jenis dan penyebab kesalahan yang mungkin ditemui pengguna saat menggunakan konektor 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 konektor developer. 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(). Kesalahan ini harus diantisipasi dan ditangani dengan penjelasan yang mudah digunakan jika perlu.

Untuk mengetahui informasi selengkapnya tentang cara menangani error internal konektor, lihat Praktik terbaik untuk menangani error konektor.

Error eksternal konektor

Error eksternal konektor terjadi setelah eksekusi konektor. Misalnya, ketika seorang Permintaan getData() untuk tiga kolom hanya menampilkan data untuk dua kolom. Meskipun konektor yang telah selesai dieksekusi, permintaan dari Looker tidak terpenuhi di Studio. Pengujian yang menyeluruh dapat mencegah error ini.

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

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 tanggal/waktu.

Jika error tidak terkait langsung dengan konektor, tidak ada tindakan untuk dilakukan oleh pengembang 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, mereka akan melihat semua detailnya. Hal ini mencakup pesan {i>error<i}, jenis kesalahan, dan pelacakan tumpukan.
• Jika pengguna bukan pengguna admin, mereka hanya akan melihat detail jika menyertakan pesan yang mudah digunakan. Untuk mempelajari lebih lanjut cara menampilkan error ke pengguna non-admin lihat Menampilkan error yang ditampilkan kepada pengguna.

Poin Penting: Terapkan isAdminUser() untuk mengidentifikasi admin sehingga tingkat ditampilkan untuk menghubungkan pengguna.

Menampilkan error yang ditampilkan kepada pengguna

Secara default, hanya admin konektor yang dapat melihat detail error. Hal ini membantu mencegah pengungkapan informasi sensitif yang tidak disengaja, seperti kunci API dalam stack rekaman aktivitas. 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 sebanyak mungkin {i>error<i} selama mengeksekusi kode konektor Anda. Misalnya, beberapa operasi umum yang mungkin menyebabkan error atau kondisi yang tidak diinginkan meliputi:

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

Menangani error yang dapat dipulihkan

Titik eksekusi konektor yang bisa gagal tetapi dapat dipulihkan harus ditangani. Misalnya, jika permintaan API gagal karena alasan non-fatal (misalnya, mengurangi beban server), maka harus dicoba lagi sebelum menampilkan {i>error<i}.

Tangkap dan tampilkan error

Error yang tidak dapat dipulihkan akan ditemukan dan ditampilkan kembali. Error yang ditampilkan ulang harus membantu pengguna memahami mengapa kesalahan itu terjadi. Jika masalah dapat diperbaiki maka detail tentang tindakan korektif harus diberikan.

Lihat menampilkan error yang ditampilkan kepada pengguna.

Mencatat error ke Stackdriver

Gunakan Stackdriver untuk logging error dan pesan lainnya. Hal ini dapat membantu memahami error, masalah proses debug, dan menemukan pengecualian yang tidak tertangani.

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

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

Perhatian: Fungsi ini tidak digunakan lagi dan akan dihapus pada Juni 2019. Memigrasi 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 keamanan untuk pengguna non-admin dan tidak disertakan dalam pesan error yang sebenarnya.

Contoh berikut mencakup kasus saat pesan error akan ditampilkan kepada pengguna non-admin lainnya di mana pesan error hanya akan ditampilkan kepada admin pengguna:

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 untuk pengguna non-admin, hal ini tidak disertakan dalam pesan error sebenarnya yang ditampilkan kepada pengguna.