Memecahkan masalah error Integrasi masalah

refresh_date: 2023-01-06

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:

  1. Pantau status project Anda dengan metrik smart home.
  2. Selidiki masalah dengan memeriksa deskripsi error mendetail di log error.

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 mengetahui adanya ketidakberaturan setelah setiap perubahan atau update pada project Anda.
  • 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 Tindakan Partner yang Dapat Dilakukan
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 di 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 Masa berlaku token akses OAuth telah berakhir 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 mencapai batas waktu.

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. Selidiki error server, waktu tunggu habis, atau error Gateway 502/503.
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 backend Anda selalu menyinkronkan Home Graph. Panggil requestSync setiap kali perangkat ditambahkan atau dihapus. 		Ya
ERROR_STATUS Respons menunjukkan status "ERROR" yang tidak spesifik tanpa kode.

Selalu sertakan string errorCode tertentu untuk meningkatkan kualitas data dasbor dan TTS pengguna. 		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.

Pastikan layanan URL endpoint stabil, benar, dan dapat diakses secara publik, serta layanan sedang berjalan. Menambahkan health check dan penanganan percobaan ulang. Selidiki error server, waktu tunggu habis, atau error Gateway 502/503. 		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). Pastikan server OAuth partner merespons permintaan refresh_token Google dengan benar untuk menerbitkan token akses baru secara lancar. 		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.

Menginstruksikan 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 secara akurat mencerminkan kemampuan perangkat.
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 diisi).

Validasi respons Anda terhadap Skema JSON Maksud. 		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 atau EXECUTE dan menampilkan semua status karakteristik yang diperlukan, meskipun tidak berubah. 		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 akunnya.

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 rasio kode ini, periksa apakah Anda juga melihat peningkatan rasio 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 pesanan 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.

Validasi struktur respons Anda berdasarkan dokumentasi developer Google Home. Pastikan respons tidak terpotong atau menampilkan isi kosong karena error server internal. 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 yang 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. Pastikan payload.commands[] adalah objek JSON yang tepat dengan ID, status, dan status opsional. 		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 ulang 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 karakteristik) 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 mengetahui apakah ada 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 speaker/peringatan 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.

Tambahkan pemetaan error yang tepat, pemeriksaan defensif, dan logging sehingga kegagalan yang diketahui menampilkan kode error tertentu, bukan kode error umum. 		Ya
UNLOCK_FAILURE Smart lock tidak dapat mencapai status "Tidak terkunci".

Selidiki gangguan hardware, baterai lemah, atau entri PIN yang tidak valid. 		Ya

Log Penelusuran

Setelah Anda merasa nyaman memantau integrasi menggunakan metrik, langkah berikutnya 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.

Mengkueri Log Cloud

Anda dapat menggunakan tombol kueri untuk membantu membuat filter kustom.

Membuat Kueri Log Cloud

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:

Sebelumnya
Cloud Logging untuk Materi