排解 Matter 整合錯誤

update_date:2023-01-06

Google Cloud 提供工具讓您使用 Google Cloud Monitoring 監控專案可靠性,以及使用 Google Cloud Logging 錯誤記錄檔進行偵錯。每當執行使用者意圖時發生失敗,Google Home Analytics (分析) 管道就會記錄指標故障,並在專案記錄檔中發布錯誤記錄。

排解錯誤的方法有兩種:

  1. 透過智慧型住宅指標監控專案狀態。
  2. 查看錯誤記錄檔中的錯誤說明,藉此調查問題。

監控錯誤

您可以使用 Google Cloud Monitoring dashboard 存取專案指標。以下幾個重要圖表特別適合用於監控品質和偵錯:

  • 「成功率」圖表是您監控專案可靠性時開始的第一個圖表。圖表中下滑可能代表部分或所有使用者服務中斷。建議您密切監控這張圖表,掌握每次變更或更新專案後是否有任何異常。
  • 就整合問題進行疑難排解時,「錯誤細目」圖表最為實用。針對您的成功百分比圖表中醒目顯示的每個錯誤,錯誤代碼都會顯示在錯誤細目中。您可以在下表中查看 Google Home platform 標記的錯誤和疑難排解方法。

平台錯誤代碼

以下是您在專案記錄中可能會看到的一些常見錯誤代碼,可找出 Google Home platform 遇到的問題。請參閱下表的疑難排解資訊。

錯誤代碼 說明
BACKEND_FAILURE_URL_ERROR Google 收到您服務傳送的 HTTP 4xx 錯誤代碼,而不是 401。

使用 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 內有多個系統隨時會將記錄傳送至您的專案。您必須編寫查詢來篩選記錄,並找出所需的記錄。查詢可以根據「時間範圍」、「資源」、記錄「嚴重性」或自訂項目。

查詢 Cloud 記錄檔

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

建構 Cloud 記錄檔查詢

如要指定「Time Range」(時間範圍),請按一下時間範圍選取按鈕 ,然後選擇其中一個提供的選項。這會篩選記錄,並顯示所選時間範圍內的記錄。

如要指定資源,請按一下「Resource」(資源) 下拉式選單,然後選擇「Google Assistant Action Project」(Google 助理動作專案)。這樣做會在查詢中新增篩選器,顯示來自專案的記錄。

使用「Severity」按鈕,即可依「Emergency」、「Info」、「Debug」和其他嚴重性記錄層級進行篩選。

您也可以使用 Logs Explorer 中的查詢欄位輸入自訂項目。這個欄位使用的查詢引擎同時支援字串比對等基本查詢,以及比較進階的查詢類型,包括比較 (<, >=, !=) 和布林運算子 (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 的使用手冊,協助您有效率地測試變更。

學習資源

本文件提供排解智慧型住宅動作錯誤的步驟。您也可以查看我們的程式碼研究室,進一步瞭解如何偵錯: