疑難排解

範例應用程式

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

收集 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. 如果點選右上角，會看到「Waiting to attach to MatterAddDeviceExtension on iPhone」。

    範例應用程式等待狀態

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

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

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

Sherlog：跨堆疊事件追蹤

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

先決條件：追蹤時必須使用 Google 協調的共用帳戶 (例如 GReg 註冊帳戶或試用帳戶)。

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

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

Fuchsia Hub 裝置記錄

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

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

  1. 傳送電子郵件給 Google 客戶技術顧問 (TAM)，並附上裝置的序號和型號。這些資訊會以小字顯示在裝置下方。
  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 應用程式 (GHA)：
    • 輕觸裝置，開啟裝置詳細資料頁面
    • 輕觸「設定」圖示 ，開啟設定頁面
    • 找出裝置 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 更新應用程式時，提交審查。

對於仍在等待 OAuth 驗證的Google Cloud應用程式，使用者必須等到驗證完成後，才能完成 OAuth 流程。嘗試授予權限時，會發生下列錯誤：

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