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 niat 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:

  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 dashboard untuk mengakses metrik project. Ada beberapa diagram utama yang sangat berguna untuk memantau kualitas dan proses debug:

  • Diagram Rasio Keberhasilan adalah diagram pertama yang harus dimulai saat Anda memantau keandalan project. Penurunan dalam diagram ini dapat menunjukkan pemadaman layanan untuk sebagian atau seluruh basis pengguna Anda. Sebaiknya pantau diagram ini dengan cermat untuk mengetahui adanya ketidaknormalan setelah setiap perubahan atau update pada project Anda.
  • Diagram Error Breakdown sangat berguna untuk memecahkan masalah pada integrasi Anda. Untuk setiap error yang ditandai dalam diagram persentase keberhasilan, kode error akan ditampilkan dalam pengelompokan error. Anda dapat melihat error yang ditandai oleh Google Home platform dan cara memecahkan masalahnya pada tabel di bawah.

Kode error platform umum

Berikut beberapa kode error umum yang mungkin Anda lihat di log project untuk mengidentifikasi masalah yang ditemukan 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 Dapat Ditindaklanjuti Partner
AGENT_ISSUE Terjadi masalah umum pada agen cloud partner.

Periksa pengecualian atau error yang tidak ditangani 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
COMMAND_FAILED Terjadi kegagalan umum selama eksekusi perintah.

Periksa log fulfillment Anda untuk menemukan requestId tertentu 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 menemukan respons 403, 404, atau 400. 		Ya
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT Waktu permintaan Google habis saat mencoba menjangkau layanan Anda.

Pastikan layanan Anda online, menerima koneksi, dan tidak melebihi kapasitas. Selain itu, pastikan perangkat target dinyalakan, online, dan disinkronkan. 		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. Gunakan requestId di Google Cloud Logging untuk memeriksa log layanan smart home Anda. 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 benar-benar 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 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 karakteristik 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 token refresh pengguna yang disimpan di Google tidak valid atau tidak dapat diperbarui, 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 ulang akun jika token dikonfirmasi telah dicabut.
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P Integrasi 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 dengan lancar. 		Ya
EXECUTION_INVALID_JSON Payload respons JSON tidak dapat diurai 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.

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 Intent. 		Ya
MALFORMED_JSON Struktur JSON rusak (misalnya, string atau objek yang tidak ditutup).

Pastikan fulfillment Anda menggunakan library JSON standar untuk melakukan serialisasi respons. 		Ya
NOT_IMPLEMENTED Intent atau karakteristik yang diminta belum diterapkan oleh partner.

Hanya sertakan ciri dalam respons SYNC yang telah Anda terapkan sepenuhnya. 		Ya
OPEN_AUTH_FAILURE Masa berlaku token akses pengguna telah berakhir 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 yang terkait dengan 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 yang valid.

Verifikasi struktur root respons fulfillment 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 terhadap 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 dihilangkan dari respons.

Pastikan respons Anda menyertakan setiap ID yang disediakan dalam payload permintaan. 		Ya
PARTNER_RESPONSE_MISSING_PAYLOAD Respons tidak memiliki kolom payload wajib.

Pastikan objek JSON tingkat teratas Anda menyertakan kunci payload. 		Ya
PARTNER_RESPONSE_NOT_OBJECT Seluruh respons tidak dapat diuraikan sebagai objek JSON.

Periksa karakter tambahan atau konten non-JSON dalam 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 karakteristik) tidak tersedia.

Periksa apakah perangkat "Sibuk" atau telah dinonaktifkan sementara. 		Ya
RESPONSE_TIMEOUT Layanan fulfillment gagal merespons dalam waktu 9 detik.

Optimalkan latensi backend; periksa kueri DB yang lambat atau keterlambatan 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 Waktu tunggu habis saat memproses intent.

Periksa log untuk mengetahui waktu tunggu layanan internal antara cloud dan hub perangkat Anda. 		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 mirip JSON dengan kolom yang berisi informasi berguna seperti waktu, kode error, dan detail terkait intent smart home asal.

Ada beberapa sistem dalam Google Cloud yang mengirim log ke project Anda setiap saat. Anda harus menulis kueri untuk memfilter log dan menemukan log yang Anda butuhkan. Kueri dapat didasarkan pada Rentang Waktu, Resource, Tingkat Keparahan log, atau entri kustom.

Membuat kueri 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 Project Action Asisten Google. 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 log keparahan lainnya.

Anda juga dapat menggunakan kolom Query 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 lanjutan, termasuk komparator (<, >=, !=) 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 guna 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 akan memandu Anda menguji perubahan secara efektif.

Materi Pembelajaran

Dokumen ini memberikan langkah-langkah untuk memecahkan masalah error di Action Smart Home Anda. Anda juga dapat melihat codelab kami untuk mempelajari lebih lanjut proses debug:

Sebelumnya
Cloud Logging untuk Materi