Google Cloud memberi Anda alat untuk memantau keandalan project dengan Google Cloud Monitoring dan men-debug masalah dengan log error Google Cloud Logging. Setiap kali terjadi kegagalan saat memenuhi maksud pengguna, pipeline Google Home Analytics akan mencatat kegagalan tersebut pada metrik Anda, dan memublikasikan log error di log project Anda.
Ada dua langkah untuk memecahkan masalah error:
- Pantau status project Anda dengan metrik smart home.
- Selidiki masalah dengan memeriksa deskripsi error mendetail di log error.
Secara opsional, Anda dapat menguji Action dengan membagikannya kepada pengguna lain. Pastikan untuk menangani error dan pengecualian dengan tepat.
Memantau error
Anda dapat menggunakan Google Cloud Monitoring dashboards untuk mengakses metrik project. Ada beberapa diagram utama yang sangat berguna untuk memantau kualitas dan melakukan proses debug:
- Diagram Tingkat Keberhasilan adalah diagram pertama yang harus dilihat saat Anda memantau keandalan project. Penurunan dalam diagram ini dapat menunjukkan gangguan untuk sebagian atau seluruh basis pengguna Anda. Sebaiknya pantau grafik ini dengan cermat untuk melihat adanya ketidakberaturan setelah setiap perubahan atau update pada project Anda.
- Diagram Latensi Persentil ke-95 adalah indikator penting untuk mengetahui performa integrasi Cloud-to-cloud bagi pengguna Anda. Fluktuasi mendadak dalam diagram ini dapat menunjukkan bahwa sistem Anda mungkin tidak dapat mengejar permintaan. Sebaiknya periksa diagram ini secara berkala untuk melihat perilaku yang tidak terduga.
- Diagram Perincian Error paling berguna untuk memecahkan masalah pada integrasi Anda. Untuk setiap error yang ditandai dalam diagram persentase keberhasilan, kode error akan ditampilkan dalam perincian error. Anda dapat melihat error yang ditandai oleh Google Home platform dan cara memecahkan masalahnya di tabel di bawah.
Kode error platform umum
Berikut beberapa kode error umum yang mungkin Anda lihat di log project untuk mengidentifikasi masalah yang terdeteksi oleh Google Home platform. Lihat tabel berikut untuk mengetahui informasi pemecahan masalah. Untuk mengetahui daftar lengkap kode error, lihat bagian Error dan pengecualian.
| Kode Error | Deskripsi | Dapat Ditindaklanjuti Partner |
|---|---|---|
ACTION_NOT_AVAILABLE |
Perintah tidak valid untuk status perangkat saat ini (misalnya,
"Setel suhu" saat perangkat dalam keadaan Nonaktif).
Verifikasi logika sifat perangkat dan status saat ini dalam pemenuhan Anda. |
Ya |
AGENT_ISSUE |
Terjadi masalah umum dengan agen cloud partner.
Periksa pengecualian atau error yang tidak tertangani dalam log pemenuhan Anda. |
Ya |
AGENT_UNAVAILABLE_ERROR |
Google tidak dapat menjangkau URL pemenuhan partner.
Pastikan server Anda online, firewall tidak memblokir Google, dan URL sudah benar. |
Ya |
APP_LAUNCH_FAILED |
Gagal meluncurkan aplikasi pihak ketiga di perangkat target.
Verifikasi appId dan pastikan aplikasi didukung di hardware target. |
Ya |
AUTH_EXPIRED |
Token akses OAuth telah habis masa berlakunya dan tidak dapat diperbarui.
Periksa rotasi token refresh dan pastikan pengguna belum mencabut akses. |
Ya |
BACKEND_FAILURE_URL_TIMEOUT |
Permintaan Google ke layanan Anda telah habis waktunya.
Pastikan layanan Anda online, menerima koneksi, dan tidak melebihi kapasitas. Selain itu, pastikan perangkat target diaktifkan, online, dan disinkronkan. |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google telah menerima kode error HTTP 5xx dari layanan Anda.
Gunakan requestId di Google Cloud Logging untuk memeriksa
log layanan smart home Anda.
|
|
CHANNEL_SWITCH_FAILED |
Perangkat tidak dapat beralih ke saluran media yang diminta.
Verifikasi nama/nomor saluran dan status langganan pengguna. |
Ya |
CHARGER_ISSUE |
Perangkat melaporkan masalah hardware pada sistem pengisian dayanya.
Partner harus menyelidiki telemetri tingkat hardware dan kesehatan baterai. |
Ya |
CHECK_PARTNER_APP |
Error ini mengharuskan pengguna membuka aplikasi partner untuk menyelesaikannya.
Gunakan kode ini untuk error yang memerlukan interaksi UI yang kompleks (misalnya, update firmware). |
Ya |
COMMAND_FAILED |
Terjadi kegagalan umum selama eksekusi perintah.
Periksa log pemenuhan Anda untuk menemukan requestId
tertentu guna menemukan akar masalahnya.
|
Ya |
COMMAND_INSERT_FAILED |
Google tidak dapat mengantrekan atau memproses perintah untuk perangkat.
Selidiki performa penulisan database atau logika antrean perintah internal. |
Ya |
DEVICE_NOT_FOUND |
ID perangkat dalam permintaan tidak ada di sisi partner.
Pastikan cloud Anda memicu requestSync saat pengguna
menambahkan atau menghapus perangkat.
|
Ya |
ERROR_STATUS |
Respons menunjukkan status "ERROR" yang tidak spesifik tanpa kode.
Selalu sertakan string errorCode tertentu untuk meningkatkan
kualitas TTS pengguna dan data dasbor.
|
Ya |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google menerima error HTTP 4xx (selain 401) dari pemenuhan
Anda.
Periksa log server web Anda untuk menemukan respons 403, 404, atau 400. |
Ya |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
URL pemenuhan diblokir oleh robots.txt atau filter keamanan.
Pastikan endpoint pemenuhan Anda dapat diakses oleh crawler/layanan Google. |
Ya |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google menerima error HTTP 5xx dari layanan pemenuhan Anda.
Selidiki error 502/503 Gateway, timeout, atau crash server. |
Ya |
EXECUTION_BAILOUT_INVALID_RESPONSE |
Respons JSON salah format sehingga pemrosesan dibatalkan.
Gunakan validator JSON untuk memastikan respons Anda secara ketat mengikuti Skema intent. |
Ya |
EXECUTION_GAL_BAD_3P_RESPONSE |
Penautan akun gagal karena format yang tidak valid dalam respons token.
Pastikan format respons server OAuth Anda cocok dengan persyaratan Google. |
Ya |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
Akun pengguna tidak memiliki izin yang diperlukan untuk tindakan ini.
Periksa cakupan yang diminta selama OAuth dan pastikan cakupan tersebut cocok dengan ciri yang diperlukan. |
Ya |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
Cloud partner menunjukkan bahwa pengguna telah membatalkan tautan akunnya.
Pastikan pemetaan agentUserId Anda stabil dan belum
dihapus.
|
Ya |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
Integrasi berada dalam status hanya baca di sisi partner.
Periksa apakah akun pengguna ditangguhkan atau dalam mode pemeliharaan "hanya lihat". |
Ya |
EXECUTION_GAL_UNLINKED_BY_3P |
Tautan akun dibatalkan secara proaktif oleh layanan pihak ketiga.
Selidiki alasan pengguna terputus (misalnya, reset keamanan). |
Ya |
EXECUTION_INVALID_JSON |
Payload respons JSON tidak dapat diuraikan oleh Google.
Periksa error sintaksis, tanda kurung yang hilang, atau karakter yang tidak valid dalam respons Anda. |
Ya |
FAULTY_BATTERY |
Hardware perangkat melaporkan bahwa baterai gagal berfungsi atau habis.
Memberi tahu pengguna menggunakan TTS atau Aplikasi untuk mengganti baterai fisik. |
Ya |
FUNCTION_NOT_SUPPORTED |
Mode atau fungsi yang diminta tidak didukung oleh perangkat.
Pastikan respons SYNC Anda mencerminkan kemampuan
perangkat secara akurat.
|
Ya |
HARD_ERROR |
Kegagalan non-sementara yang tidak akan terselesaikan tanpa intervensi manual.
Gunakan ini untuk kegagalan hardware permanen atau status akun yang tidak dapat dipulihkan. |
Ya |
INVALID_AUTH_TOKEN |
Google telah menerima kode error HTTP 401 dari layanan Anda.
Masa berlaku token akses belum berakhir, tetapi layanan Anda telah membatalkan validasinya. Gunakan requestId di Google Cloud Logging untuk memeriksa log layanan smart home Anda.
|
|
INVALID_JSON |
Struktur respons tidak valid (misalnya, tidak ada kolom
wajib).
Validasi respons Anda terhadap Skema JSON Intent. |
Ya |
LOCK_FAILURE |
Smart lock tidak dapat beralih ke status yang diminta.
Selidiki gangguan fisik, daya rendah, atau kegagalan motor pada hardware smart lock. |
Ya |
MALFORMED_JSON |
Struktur JSON rusak (misalnya, string atau objek tidak ditutup).
Pastikan fulfillment Anda menggunakan library JSON standar untuk melakukan serialisasi respons. |
Ya |
MISSING_STATE |
Respons QUERY tidak berisi status perangkat yang diminta.
Pastikan semua karakteristik yang ditentukan dalam SYNC diperhitungkan dalam
setiap respons QUERY.
|
Ya |
NETWORK_PROFILE_NOT_RECOGNIZED |
Profil jaringan yang diminta tidak diketahui oleh perangkat.
Verifikasi bahwa string nama profil cocok dengan profil yang didukung dalam respons SYNC.
|
Ya |
NOT_IMPLEMENTED |
Intent atau sifat yang diminta belum diterapkan oleh partner.
Hanya sertakan ciri dalam respons SYNC yang telah
Anda terapkan sepenuhnya.
|
Ya |
OAUTH_RECONNECT_CALL_TO_ACTION |
Memicu notifikasi bagi pengguna untuk menautkan kembali akun mereka.
Gunakan ini saat sesi pengguna dibatalkan dan memerlukan otorisasi ulang OAuth secara manual. |
Ya |
OPEN_AUTH_FAILURE |
Token akses pengguna telah habis masa berlakunya dan Google tidak dapat memperbaruinya,
atau Google telah menerima kode error HTTP 401 dari layanan Anda.
Jika Anda melihat peningkatan frekuensi kode ini, periksa apakah Anda juga melihat peningkatan frekuensi error terkait permintaan token refresh atau intent smart home. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
String errorCode yang ditampilkan tidak ada dalam daftar yang didukung Google.
Petakan error internal Anda ke Daftar Error Resmi. |
Ya |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Kolom payload dalam respons bukan objek JSON yang valid.
Verifikasi struktur root respons pemenuhan Anda. |
Ya |
PARTNER_RESPONSE_INVALID_STATUS |
Respons status bukan SUCCESS, ERROR, atau OFFLINE.
Pastikan setiap hasil perangkat dalam respons Anda menyertakan string status yang valid. |
Ya |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Respons tidak menyertakan hasil untuk semua perintah/perangkat yang diminta.
Setiap item dalam array commands permintaan harus memiliki
entri respons yang sesuai.
|
Ya |
PARTNER_RESPONSE_MISSING_DEVICE |
Perangkat tertentu yang diminta oleh Google tidak disertakan dalam respons.
Pastikan respons Anda menyertakan setiap ID yang diberikan dalam
payload permintaan.
|
Ya |
PARTNER_RESPONSE_MISSING_PAYLOAD |
Respons tidak memiliki kolom payload wajib diisi.
Pastikan objek JSON tingkat teratas Anda menyertakan kunci payload.
|
Ya |
PARTNER_RESPONSE_NOT_OBJECT |
Seluruh respons tidak dapat diuraikan sebagai objek JSON.
Periksa karakter di akhir atau konten non-JSON dalam isi respons HTTP Anda. |
Ya |
PROTOCOL_ERROR |
Terjadi error dalam protokol komunikasi yang mendasarinya.
Selidiki masalah header HTTP atau kegagalan handshake SSL/TLS. |
Ya |
RELINK_REQUIRED |
Pengguna harus menautkan kembali akunnya untuk terus menggunakan integrasi.
Pastikan server Anda menampilkan kode ini saat token refresh tidak valid secara permanen. |
Ya |
REQUEST_ID_NOT_FOUND |
Google tidak dapat menemukan ID pelacakan internal untuk permintaan tersebut.
Biasanya merupakan error platform internal; pantau lonjakan dan hubungi dukungan. |
Ya |
RESOURCE_UNAVAILABLE |
Resource yang diminta (perangkat atau sifat) tidak tersedia.
Periksa apakah perangkat "Sibuk" atau telah dinonaktifkan sementara. |
Ya |
RESPONSE_TIMEOUT |
Layanan pemenuhan gagal merespons dalam waktu 9 detik.
Mengoptimalkan latensi backend; periksa kueri DB yang lambat atau keterlambatan jaringan regional. |
Ya |
RESPONSE_UNAVAILABLE |
Tidak ada respons yang diterima dari URL pemenuhan partner.
Pastikan layanan Anda berjalan dan endpoint tidak mengalami error. |
Ya |
SCENE_CANNOT_BE_APPLIED |
Adegan yang diminta tidak dapat diaktifkan (misalnya, perangkat
tidak ada).
Periksa kondisi internal adegan pengguna di cloud partner. |
Ya |
STREAM_UNPLAYABLE |
Streaming kamera tidak dapat dimulai atau telah gagal.
Verifikasi sinyal WebRTC/HLS dan pastikan URL streaming valid. |
Ya |
TIMEOUT |
Terjadi waktu tunggu habis umum saat memproses maksud.
Periksa log untuk waktu tunggu layanan internal antara cloud dan hub perangkat Anda. |
Ya |
TRANSIENT_ERROR |
Error sementara adalah error yang akan teratasi dengan sendirinya.
Biasanya, error ini muncul sebagai koneksi ke perangkat atau layanan yang terputus. Juga jika koneksi baru ke server tidak dapat dibuka. |
|
UNABLE_TO_LOCATE_DEVICE |
Perangkat tidak dapat ditemukan menggunakan trait Locator (misalnya,
ping gagal).
Periksa konektivitas lokal perangkat (Wi-Fi/Bluetooth). |
Ya |
UNABLE_TO_RING_DEVICE |
Perangkat dapat dijangkau, tetapi tidak dapat memicu fungsi dering/notifikasinya.
Verifikasi status peringatan/speaker dan tingkat volume hardware. |
Ya |
UNABLE_TO_SILENCE_DEVICE |
Perangkat tidak dapat menghentikan notifikasi/dering yang aktif.
Menyelidiki kegagalan komunikasi antara cloud dan perangkat fisik. |
Ya |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
Terjadi error yang tidak terduga; pengguna harus memeriksa aplikasi partner.
Gunakan sebagai penampung untuk error yang tidak memiliki padanan khusus yang didukung Google. |
Ya |
UNKNOWN_ERROR |
Kegagalan umum tanpa detail tambahan yang diberikan.
Ganti dengan kode error yang lebih spesifik untuk meningkatkan pemecahan masalah. |
Ya |
UNLOCK_FAILURE |
Smart lock tidak dapat mencapai status "Unlocked".
Selidiki gangguan hardware, baterai lemah, atau entri PIN yang tidak valid. |
Ya |
Log Penelusuran
Setelah Anda merasa nyaman memantau integrasi menggunakan metrik, langkah selanjutnya adalah memecahkan masalah error tertentu menggunakan Cloud Logging. Log error adalah entri seperti JSON dengan kolom yang berisi informasi berguna seperti waktu, kode error, dan detail terkait maksud smart home yang berasal.
Ada beberapa sistem dalam Google Cloud yang mengirim log ke project Anda setiap saat. Anda perlu menulis kueri untuk memfilter log dan menemukan log yang Anda butuhkan. Kueri dapat didasarkan pada Rentang Waktu, Resource, Tingkat Keparahan log, atau entri kustom.
Anda dapat menggunakan tombol kueri untuk membantu membuat filter kustom.
Untuk menentukan Rentang Waktu, klik tombol pemilihan rentang waktu dan pilih salah satu opsi yang tersedia. Tindakan ini akan memfilter log dan menampilkan log yang berasal dari rentang waktu yang dipilih.
Untuk menentukan Resource, klik dropdown Resource, lalu pilih Google Assistant Action Project. Tindakan ini akan menambahkan filter dalam kueri Anda untuk menampilkan log yang berasal dari project Anda.
Gunakan tombol Severity untuk memfilter menurut Emergency, Info, Debug, dan tingkat log severity lainnya.
Anda juga dapat menggunakan kolom Kueri di Logs Explorer
untuk memasukkan entri kustom. Mesin kueri yang digunakan oleh kolom ini mendukung
kueri dasar seperti pencocokan string, dan jenis kueri yang lebih canggih termasuk
pembanding (<, >=, !=) dan operator boolean (AND, OR, NOT).
Misalnya, entri kustom di bawah akan menampilkan error yang
berasal dari jenis perangkat LIGHT:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
Buka Pustaka Kueri untuk menemukan contoh lainnya tentang cara membuat kueri log secara efektif.
Menguji Perbaikan
Setelah Anda mengidentifikasi error dan menerapkan update untuk memperbaikinya, sebaiknya uji perbaikan Anda secara menyeluruh dengan Google Home Test Suite. Kami menyediakan panduan pengguna tentang cara menggunakan Test Suite, yang memandu Anda menguji perubahan secara efektif.
Materi Pembelajaran
Dokumen ini memberikan langkah-langkah untuk memecahkan masalah error di Smart Home Action Anda. Anda juga dapat melihat codelab kami untuk mempelajari lebih lanjut cara men-debug:
- Codelab Debugging Smart Home: Panduan memulai cepat untuk men-debug integrasi cloud smart home.
- Codelab Proses Men-debug Local Home: Panduan memulai cepat untuk men-debug integrasi lokal smart home.