疑難排解

範例應用程式

如果使用 Google Home API 時遇到任何問題，可以收集記錄以利進一步偵錯。如要從行動裝置收集記錄，必須使用 Xcode。 如需 Google 協助，請從 iOS 裝置和中樞裝置收集記錄，並在問題追蹤器中開啟支援單，附上相關資訊和記錄。

收集 iOS 記錄

在涉及 Xcode 的所有步驟中，行動裝置都必須連線至本機電腦。

應用程式記錄和 SDK 記錄會直接顯示在 Xcode 控制台中，並可供收集。行動裝置連上本機電腦後，透過 Xcode 執行應用程式時，控制台會自動擷取並串流處理應用程式層和整合式 Home SDK 的標準輸出 (stdout) 和標準錯誤 (stderr) 記錄。在開發和偵錯期間，您可以透過這種簡單的方式，監控即時初始化程序、API 互動和 SDK 事件。

從 Xcode 收集擴充功能記錄

如果使用 Home API 時遇到任何問題，可以收集記錄，以利進一步偵錯。

  1. 在 Xcode 中，前往頂端選單列的「Debug」，然後按一下「Attach to Process by PID or Name」。

    範例應用程式偵錯

  2. 在「PID or Process Name」下方，選取「MatterExtension」，然後按一下「Attach」。

    範例應用程式附加額外資訊

  3. 按一下右上角時，你會看到「等待附加至 iPhone 上的 MatterAddDeviceExtension」。

    範例應用程式等待狀態

  4. 按一下分頁標籤，然後選取「MatterAddExtension」MatterAddExtension。

    新增 Matter 擴充功能的範例應用程式

  5. 控制台會記錄擴充功能記錄。

Sherlog：跨堆疊事件追蹤

Sherlog 是一項即時追蹤服務，可提供 Google 基礎架構與合作夥伴雲端服務之間互動的端對端檢視畫面。

必要條件：如要追蹤，必須使用 Google 協調的共用帳戶 (例如 GReg 註冊或示範帳戶)。

核心用途：偵錯功能缺陷和雲端對雲端 (C2C) 整合問題 (例如帳戶連結失敗或裝置狀態錯誤)，無須變更正式版程式碼。

功能：提供完整的 RPC 呼叫圖表、要求/回應酬載，以及 SYNC、EXECUTE、QUERY 和帳戶連結意圖的中繼資料。

Fuchsia 中樞裝置記錄

你可以使用這個方法，從下列 Fuchsia 中樞裝置收集記錄： * Google Nest Hub (第 2 代) * Google Nest Hub Max

如要啟用中樞，以便擷取本機記錄，請按照下列步驟操作：

  1. 將裝置的序號和型號透過電子郵件傳送給 Google 客戶技術顧問。這些資訊會以小字顯示在裝置下方。
  2. 列入許可清單後，請按照下列步驟啟用這項功能：
    • 從中樞裝置：
      1. 從畫面頂端向下滑動。
      2. 輕觸「設定」圖示
      3. 找出 Fuchsia 版本：在 Nest Hub (第 2 代) 上，依序前往「裝置資訊」>「技術資訊」>「Fuchsia 版本」
      4. 輕觸「Fuchsia 版本」7 次。這樣就會啟用開發人員選項
      5. 返回頂層選單
      6. 輕觸「開發人員選項」
      7. 輕觸「合作夥伴記錄」
    • 這項功能將啟用 24 小時。然後從步驟 5 開始，重新啟用記錄功能。
  3. 取得中樞的 IP 位址：
    • 如果中樞裝置有螢幕：
      1. 從畫面頂端向下滑動。
      2. 輕觸「設定」圖示
      3. 找出裝置 IP 位址：在 Nest Hub (第 2 代) 上，依序前往「裝置資訊」>「技術資訊」>「IP 位址」
    • 透過手機上的 Google Home 應用程式：
    • 輕觸裝置，開啟裝置詳細資料頁面
    • 輕觸「設定」圖示 ，開啟設定頁面
    • 找出裝置 IP 位址：依序前往「裝置資訊」>「技術資訊」>「IP 位址」
  4. 如要從中樞裝置擷取記錄，請透過連上相同 Wi-Fi 網路的電腦，對中樞裝置發出 GET HTTP 要求。
    • 記下端點的通訊埠和路徑：
      curl -k -X GET https://ip-address:8443/setup/get_logs --output output-file
    • 連線只能保持開啟一分鐘，但從緩衝區擷取的資料通常包含過去 20 到 30 分鐘的事件。
      • 理想情況下，您應在完成測試程序後立即使用這個方法擷取記錄，確保緩衝區包含與測試相關的內容 (類似於 Android 錯誤報告)。

自動化動作

邊緣偵測

Google Home 生態系統中的自動化動作採用邊緣偵測，這項邏輯會驗證啟動條件是否只在實際狀態變更時啟動，而非在狀態更新時啟動 (狀態更新只會重複裝置先前的狀態)。

舉例來說，如果開啟燈具是啟動條件，邊緣偵測功能會驗證啟動條件是否只在燈具從關閉變成開啟時啟動，而不是從開啟變成開啟 (沒有變化)。

自動化動作不如預期

考量邊緣偵測後，如果自動化動作未如預期運作，請採取下列行動：

  1. 檢查每部裝置，確認裝置是否能獨立運作，不受自動化動作影響。

  2. 查看自動化動作的自動化圖表，並與自動化動作 DSL 比較，找出您可能做出的錯誤假設。

  3. 在執行自動化動作期間，透過 Google Home 應用程式觀察裝置狀態。

  4. 確認自動化動作參照的所有裝置都位於預期位置的結構中。如果自動化動作依附的裝置遭到刪除，可能會導致意想不到的後果。請參閱刪除裝置對自動化作業的影響。

自動化動作不應執行

如果自動化動作在不應啟動時啟動，請檢查啟動條件。 您可能需要新增額外邏輯，確保系統只擷取一次狀態變更，且只觸發一次自動化動作。

自動化動作無法編譯

請確認應用程式包含所有必要匯入項目，包括對應不同節點類型的各個類別，以及您參照的特徵。

自動化作業建立失敗，驗證未通過

如果自動化建立作業未通過驗證，系統會顯示警告或錯誤訊息，說明問題。詳情請參閱ValidationIssueType參考資料。

OAuth

如果您有現有的 OAuth 用戶端

如果您已為發布的應用程式建立經過驗證的 OAuth 用戶端，可以使用現有的 OAuth 用戶端測試 Home API。

如要測試及使用 Home API，不需要進行 Google Home Developer Console 註冊。 不過，即使您有來自其他整合服務的已驗證 OAuth 用戶端，仍須通過Developer Console註冊核准，才能發布應用程式。

請注意下列事項：

  • 使用現有 OAuth 用戶端時，使用者人數上限為 100 人。如要瞭解如何新增測試使用者，請參閱「產生 OAuth 用戶端 ID」。 除了 OAuth 驗證外，Home API 也設下限制，最多只能有 100 位使用者授予應用程式權限。完成 Developer Console 註冊後，這項限制就會解除。

  • Developer Console 註冊 準備透過 OAuth 限制裝置類型授權，以便更新應用程式並使用 Home API 時，應送交審核。

如果 Google Cloud 應用程式的 OAuth 驗證仍在待處理狀態，使用者必須等到驗證完成，才能完成 OAuth 流程。嘗試授予權限時會失敗，並顯示下列錯誤訊息：

Access blocked: <Project Name> has not completed the Google verification process.