refresh_date: 2023-01-06
Google Cloud menyediakan alat untuk memantau keandalan project Anda dengan Google Cloud Monitoring dan men-debug masalah dengan Google Cloud Logging log error. Setiap kali terjadi kegagalan saat memenuhi intent 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 Anda:
- Pantau status project Anda dengan metrik smart home.
- Selidiki masalah dengan memeriksa deskripsi error mendetail di log error.
Memantau error
Anda dapat menggunakan Google Cloud Monitoring dashboards untuk mengakses metrik project Anda. Ada beberapa diagram utama yang sangat berguna untuk memantau kualitas dan men-debug:
- Diagram Tingkat Keberhasilan adalah diagram pertama yang harus dilihat saat Anda memantau keandalan project Anda. Penurunan dalam diagram ini dapat menunjukkan gangguan untuk sebagian atau seluruh basis pengguna Anda. Sebaiknya pantau diagram ini dengan cermat untuk mengetahui adanya ketidakberaturan setelah setiap perubahan atau update pada project Anda.
- Diagram Perincian Error paling berguna saat memecahkan masalah pada integrasi Anda. Untuk setiap error yang ditandai dalam diagram persentase keberhasilan Anda, kode error akan ditampilkan dalam perincian error Anda. Anda dapat melihat error yang ditandai oleh Google Home platform dan cara memecahkannya dalam tabel di bawah.
Kode error platform umum
Berikut beberapa kode error umum yang mungkin Anda lihat di log project Anda untuk mengidentifikasi masalah yang ditangkap oleh Google Home platform. Lihat tabel berikut untuk mengetahui informasi pemecahan masalah. Untuk mengetahui daftar lengkap kode error, lihat Error dan pengecualian.
| Kode Error | Deskripsi | Tindakan yang Dapat Dilakukan Partner |
|---|---|---|
AGENT_ISSUE |
Terjadi masalah umum dengan agen cloud partner.
Periksa pengecualian atau error yang tidak tertangani di log fulfillment Anda. |
Ya |
AGENT_UNAVAILABLE_ERROR |
Google tidak dapat menjangkau URL fulfillment partner.
Pastikan server Anda online, firewall tidak memblokir Google, dan URL sudah benar. |
Ya |
BACKEND_FAILURE_URL_TIMEOUT |
Permintaan Google mengalami error waktu tunggu saat mencoba menjangkau layanan Anda.
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,
atau error Gateway 502/503.
|
|
COMMAND_FAILED |
Terjadi kegagalan umum selama eksekusi perintah.
Periksa log fulfillment Anda untuk requestId
guna menemukan akar masalahnya.
|
Ya |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google menerima error HTTP 4xx (selain 401) dari
fulfillment Anda.
Periksa log server web Anda untuk mengetahui respons 403, 404, atau 400. |
Ya |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
URL fulfillment diblokir oleh robots.txt atau filter keamanan.
Pastikan endpoint fulfillment Anda dapat diakses oleh crawler/layanan Google. |
Ya |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google menerima error HTTP 5xx dari layanan fulfillment Anda.
Pastikan layanan URL endpoint stabil, benar, dan dapat dijangkau secara publik, serta layanan berjalan. Tambahkan health check dan penanganan percobaan ulang. Selidiki error server, waktu tunggu, atau error Gateway 502/503. |
Ya |
EXECUTION_BAILOUT_INVALID_RESPONSE |
Respons JSON sangat salah format sehingga pemrosesan dibatalkan.
Gunakan validator JSON untuk memastikan respons Anda mengikuti skema Intent secara ketat. |
Ya |
EXECUTION_GAL_BAD_3P_RESPONSE |
Penautan akun gagal karena format yang tidak valid dalam respons token.
Pastikan format respons server OAuth Anda sesuai 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 fitur 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_NOT_FOUND |
Token akses dan refresh pengguna yang disimpan di Google tidak valid atau
tidak dapat di-refresh, sehingga mencegah autentikasi dan akses ke
layanan partner.
Pastikan token tetap valid dan disinkronkan, tangani perubahan status akun dengan tepat, dan minta pengguna untuk menautkan kembali akun jika token dikonfirmasi telah dicabut. |
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 |
Akun secara proaktif dibatalkan tautannya 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 tidak ada, atau karakter yang tidak valid dalam respons Anda. |
Ya |
INVALID_AUTH_TOKEN |
Google telah menerima kode error HTTP 401 dari layanan Anda.
Token akses belum habis masa berlakunya, tetapi layanan Anda telah membatalkannya. Gunakan requestId di Google Cloud Logging untuk memeriksa log layanan smart home Anda.
|
|
INVALID_JSON |
Struktur respons tidak valid (misalnya, kolom wajib tidak ada
).
Validasi respons Anda terhadap Skema JSON Intent. |
Ya |
MALFORMED_JSON |
Struktur JSON rusak (misalnya, string atau
objek tidak tertutup).
Pastikan fulfillment Anda menggunakan library JSON standar untuk membuat serialisasi respons. |
Ya |
NOT_IMPLEMENTED |
Intent atau fitur yang diminta belum diimplementasikan oleh partner.
Hanya sertakan fitur dalam respons SYNC yang telah Anda
implementasikan sepenuhnya.
|
Ya |
OPEN_AUTH_FAILURE |
Token akses pengguna telah habis masa berlakunya dan Google tidak dapat me-refresh-nya,
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 intent smart home atau permintaan token refresh. |
|
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
objek yang valid.
Verifikasi struktur root respons fulfillment Anda. |
Ya |
PARTNER_RESPONSE_INVALID_STATUS |
status respons 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 terhadap dokumentasi developer Google Home documentation. 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 dihilangkan dari respons.
Pastikan respons Anda menyertakan setiap ID yang diberikan dalam
payload permintaan.
|
Ya |
PARTNER_RESPONSE_MISSING_PAYLOAD |
Respons tidak memiliki kolom payload wajib.
Pastikan objek JSON tingkat atas Anda menyertakan kunci payload.
|
Ya |
PARTNER_RESPONSE_NOT_OBJECT |
Seluruh respons tidak dapat diuraikan sebagai objek JSON.
Periksa karakter tambahan atau konten non-JSON di isi respons HTTP Anda. Pastikan payload.commands[] adalah objek JSON yang tepat dengan ID, status, dan status opsional.
|
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 fitur) tidak tersedia.
Periksa apakah perangkat "Sedang Digunakan" atau telah dinonaktifkan untuk sementara. |
Ya |
RESPONSE_TIMEOUT |
Layanan fulfillment gagal merespons dalam waktu 9 detik.
Optimalkan latensi backend; periksa kueri DB yang lambat atau latensi jaringan regional. |
Ya |
RESPONSE_UNAVAILABLE |
Tidak ada respons yang diterima dari URL fulfillment partner.
Pastikan layanan Anda berjalan dan endpoint tidak mengalami error. |
Ya |
TIMEOUT |
Terjadi waktu tunggu umum saat memproses intent.
Periksa log untuk waktu tunggu layanan internal antara cloud dan hub perangkat Anda. |
Ya |
Log Penelusuran
Setelah Anda terbiasa 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 intent 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 disediakan. 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 berdasarkan Emergency, Info, Debug, dan tingkat keparahan log lainnya.
Anda juga dapat menggunakan kolom Kueri di Logs Explorer
untuk memasukkan entri kustom. Mesin kueri yang digunakan oleh kolom ini mendukung baik
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 Library 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 menyediakan langkah-langkah untuk memecahkan masalah error di Smart Home Action Anda. Anda juga dapat melihat codelab kami untuk mempelajari lebih lanjut tentang proses debug:
- Codelab Debugging Smart Home: Panduan memulai dengan cepat untuk men-debug integrasi cloud smart home.
- Codelab Debugging Local Home: Panduan memulai dengan cepat untuk men-debug integrasi lokal smart home.