Google Cloud 提供的工具可讓您使用 Google Cloud Monitoring 監控專案的穩定性,並透過 Google Cloud Logging 錯誤記錄檔進行偵錯。如果完成使用者意圖失敗,Google Home Analytics (分析) 管道會將指標記錄失敗,並在專案記錄中發布錯誤記錄檔。
排解錯誤時,共有兩個步驟:
- 透過智慧型住宅指標監控專案狀態。
- 查看錯誤記錄檔中的詳細錯誤說明,即可調查問題。
監控錯誤
您可以使用 Google Cloud Monitoring dashboard 存取專案指標。以下幾個重要圖表特別適合用於監控品質和偵錯:
- 「Success Rate」(成功率) 圖表是您監控專案可靠性時最先開始的圖表。圖表中的下降可能代表部分或所有使用者服務中斷。建議您在每次專案變更或更新專案後,密切監控此圖表以觀察任何異常狀況。
- 「第 95 個百分位數的延遲時間」圖表是智慧型住宅動作對使用者執行效能的重要指標。圖表中如果突然出現波動,可能表示您的系統可能無法跟上要求。建議定期查看此圖表,看看是否有任何非預期的行為。
- 解決整合問題時,「錯誤細目」圖表最為實用。對於成功百分比圖表中醒目顯示的每個錯誤,錯誤細目都會顯示一個錯誤代碼。您可以在下表中查看 Google Home platform 標記的錯誤,以及疑難排解方式。
平台錯誤代碼
以下是專案記錄中可能會顯示的一些常見錯誤代碼,方便您找出 Google Home platform 發現的問題。如需疑難排解資訊,請參閱下表。
錯誤代碼 | 說明 |
---|---|
BACKEND_FAILURE_URL_ERROR |
Google 已從您的服務收到 401 以外的 HTTP 4xx 錯誤代碼。
您可以使用 GCP Logging 中的 requestId ,查看智慧型居家服務記錄檔。 |
BACKEND_FAILURE_URL_TIMEOUT |
Google 嘗試連線至您的服務時的要求逾時。
確認服務已連線、接受連線,且未超出容量。此外,請確認目標裝置已開機、已連線並保持同步。 |
BACKEND_FAILURE_URL_UNREACHABLE |
Google 從您的服務收到 HTTP 5xx 錯誤代碼。
您可以使用 GCP Logging 中的 requestId ,查看智慧型居家服務記錄檔。 |
DEVICE_NOT_FOUND |
合作夥伴服務端沒有這部裝置。
這通常表示資料同步處理失敗或競爭狀況。 |
GAL_BAD_3P_RESPONSE |
由於酬載中的格式或值無效,Google 無法剖析帳戶連結服務所提供的回應。 使用 GCP Logging 中的 requestId ,查看帳戶連結服務中的錯誤記錄檔。 |
GAL_INTERNAL |
Google 嘗試擷取存取權杖時發生 Google 內部錯誤。 如果您在 GCP Logging 中發現這個錯誤的比率提高,請與我們聯絡以取得更多資訊。 |
GAL_INVALID_ARGUMENT |
Google 嘗試擷取存取權杖時發生 Google 內部錯誤。 如果您在 GCP Logging 中發現這個錯誤的比率提高,請與我們聯絡以取得更多資訊。 |
GAL_NOT_FOUND |
使用者儲存在 Google 中的存取權杖和更新權杖會失效,且無法再重新整理。使用者必須重新連結帳戶,才能繼續使用服務。
如果您在 GCP Logging 中發現這個錯誤的比率提高,請與我們聯絡以取得更多資訊。 |
GAL_PERMISSION_DENIED |
權杖共用未獲授權時,發生 Google 內部錯誤。 如果您在 GCP Logging 中發現這個錯誤的比率提高,請與我們聯絡以取得更多資訊。 |
GAL_REFRESH_IN_PROGRESS |
使用者的存取權杖已過期,且正在嘗試再次重新整理權杖。 這不是問題,您不需要採取任何行動。 |
INVALID_AUTH_TOKEN |
Google 已從您的服務收到 HTTP 401 錯誤代碼。 存取權杖並未過期,但您的服務已失效。 您可以使用 GCP Logging 中的 requestId 查看智慧型居家服務記錄檔。 |
INVALID_JSON |
系統無法剖析或解讀 JSON 回應。 檢查 JSON 回應的結構是否有無效的語法,例如括號不符、缺少逗號和無效的字元。 |
OPEN_AUTH_FAILURE |
使用者的存取權杖已過期,且 Google 無法重新整理權杖,或是 Google 從您的服務收到 HTTP 401 錯誤代碼。 如果您看見這個程式碼的發生頻率增加,請檢查智慧型住宅意圖的錯誤率是否也提高,或是更新權杖要求。 |
PARTNER_RESPONSE_INVALID_ERROR_CODE |
回應表示無法辨識的錯誤代碼。
如果您的要求回應指出錯誤,請務必使用 支援的錯誤代碼提供的一個回應。 |
PARTNER_RESPONSE_INVALID_PAYLOAD |
回應 payload 欄位無法剖析為 JSON 物件。檢查要求回應中的酬載欄位是否包含相符的括號,以及是否以 JSON 欄位的形式正確結構。 |
PARTNER_RESPONSE_INVALID_STATUS |
回應不含狀態或指出錯誤狀態。 對意圖執行要求的回應應以 SUCCESS, OFFLINE, ERROR, EXCEPTIONS 表示狀態。您可以參閱
這篇文章,進一步瞭解如何處理錯誤和例外狀況。 |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
回應中缺少要求中的一或多個意圖。 確認 執行回應的結構正確無誤,而且您的要求中包含要求中所有意圖的結果。 |
PARTNER_RESPONSE_MISSING_DEVICE |
回應中缺少要求中的一或多部裝置。 確認您的 執行回應結構正確,且回應中顯示要求中的所有裝置 ID。 |
PARTNER_RESPONSE_MISSING_PAYLOAD |
回應中不含 payload 欄位。請務必在要求回應中加入酬載欄位。進一步瞭解如何正確建構 執行回應。 |
PARTNER_RESPONSE_NOT_OBJECT |
無法將回應剖析為 JSON 物件。 檢查要求回應中的所有欄位,確認其中是否有非預期的字元、括號不符或格式錯誤。部分萬國碼 (Unicode) 字元可能不受支援。此外,請確認您的回應已正確建構為 JSON 物件。 |
PROTOCOL_ERROR |
處理要求失敗。
您可以透過 Google Cloud Logging 中的 requestId 查看智慧型住宅服務記錄檔。
|
RESPONSE_TIMEOUT |
要求已在等候回應時逾時。 傳送回應的時限為傳送要求後的 9 秒。請務必在期限內送出回覆。 |
RESPONSE_UNAVAILABLE |
沒有收到回應,或回應未指出狀態。
回應意圖執行要求的回應應根據 智慧型住宅文件妥善建構,並標明狀態。 |
TRANSIENT_ERROR |
暫時性錯誤會自行解決。 這類錯誤通常會出現在裝置或服務中斷時,也無法開啟連至伺服器的新連線。 |
搜尋記錄
在使用指標監控整合作業後,下一步就是使用 Cloud Logging 排解特定錯誤。錯誤記錄是類似 JSON 的項目,內含一些實用資訊,例如時間、錯誤代碼和來源智慧住宅意圖的詳細資料。
Google Cloud 中有多個系統會隨時將記錄檔傳送至您的專案。您必須撰寫查詢來篩選記錄,然後找出所需記錄。查詢可根據「時間範圍」、「資源」、記錄「嚴重性」或自訂項目。

您可以使用查詢按鈕建立自訂篩選器。

如要指定「Time Range」(時間範圍),請按一下時間範圍選取按鈕
,然後選擇其中一個提供的選項。這麼做會篩選記錄,並顯示所選時間範圍內產生的記錄。如要指定資源,請按一下「Resource」下拉式選單,然後選擇「Google Assistant Action Project」。這樣會在查詢中新增篩選器,顯示源自專案的記錄。
使用「嚴重程度」按鈕,即可按照「緊急」、「資訊」、「偵錯」和其他嚴重性記錄等級進行篩選。
您也可以使用 Logs Explorer 中的「Query」(查詢) 欄位輸入自訂項目。此欄位使用的查詢引擎支援字串比對等基本查詢,以及更多進階查詢類型,包括比較器 (<, >=, !=
) 和布林運算子 (AND, OR, NOT
)。
例如,以下自訂項目會傳回源自 LIGHT
裝置類型的錯誤:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
請前往查詢程式庫,查看更多能有效查詢記錄的範例。
測試修正結果
找出錯誤並套用更新以修正問題後,建議您使用 Google Home Test Suite 全面測試修正後的結果。我們提供了 Test Suite 使用手冊,協助您有效率地測試變更。
學習資源
本文件提供排解智慧型住宅動作錯誤的步驟。您也可以查看我們的程式碼研究室,進一步瞭解如何偵錯:
- 對智慧型住宅雲端程式碼研究室進行偵錯:為智慧型住宅雲端整合偵錯的快速入門指南。
- 對本機住家程式碼研究室進行偵錯:針對智慧型住宅本機整合進行偵錯的快速入門指南。