Google Home Vitals (Cloud)

這套資訊主頁和快訊可協助您主動維護與 Google Home 生態系統的高品質整合。Google 致力於協助合作夥伴為所有消費者開發高品質的生態系統。

資訊主頁分為三個部分，分別涵蓋影響整體整合品質的重要環節。

1. Google 至合作夥伴指標：評估從 Google 到雲端後端的呼叫健康狀態。

2. 系統健康狀態 - 合作夥伴至 Google 指標 - 評估從系統到 Google 的呼叫健康狀態。

3. 裝置健康狀態 - 狀態準確度：評估 Google 系統儲存狀態的準確度，這些狀態用於處理使用者查詢。

如果指標未達到目標值，系統會以紅色醒目顯示，表示可能影響使用者體驗的問題。以下資訊詳細說明各個目標，以及這些目標對使用者的重要性。

如果按下方按鈕後沒有直接前往資訊主頁，請選取「總覽」頁面，然後選取「資訊主頁」，並從「我的資訊主頁」清單中選取「Google Home Vitals 資訊主頁 (Cloud)」，即可查看資訊主頁。

前往資訊主頁

Google 傳送給合作夥伴的指標

「查詢/執行成功率 >= 99.5%」指標會評估使用者指令的正確執行頻率，有助於避免 Google 助理回覆「我無法連上裝置」等訊息，或錯誤確認尚未執行的指令。

「成功」的定義為何？

如果 Google Home 平台收到有效的回應，指出已完成預期動作或擷取要求的狀態，系統就會將交易標示為成功。

如果回應包含非封鎖例外狀況 (例如 SUCCESS 狀態和 lowBattery 例外狀況)，系統會將其計為成功交易。指令已傳送至裝置，且意圖已滿足，但發生警告。

什麼是「失敗」？

計算 QUERY 和 EXECUTE 成功率時，常見平台錯誤代碼中標示為「合作夥伴可採取行動」的錯誤會視為「失敗」。此外，錯誤和例外狀況中列出的錯誤也會視為「失敗」，但下列情況除外：

「查詢/執行延遲時間 (p90) <= 1000 毫秒」指標會測量要求動作的等待時間，確保使用者不必等待太久，例如等待幾秒鐘讓燈光關閉。

延遲指標

延遲時間是重要指標，可反映整合服務對終端使用者的回應速度。資訊主頁會追蹤第 90 個百分位數 (P90) 的延遲時間，代表「最慢」使用者的體驗 (舉例來說，P90 為 800 毫秒表示 90% 的要求會在 800 毫秒內獲得確認)。

為確保技術準確度，Google 會以不同方式測量狀態檢查和裝置指令的延遲時間。

1. 查詢延遲 (疑問)

這項指標會測量 Google 要求裝置目前狀態時的Cloud-to-cloud往返時間。

• 開始：Google 會將 action.devices.QUERY 要求傳送至你的完成網址。
• 測量時間範圍：雲端接收、處理及將完整 HTTP 回應傳輸回 Google 所需的時間。
• 結束：Google 收到並確認來自您服務的最終回應酬載。

2. EXECUTE 延遲時間 (動作)

這項指標會測量 Google 將控制要求傳送至裝置時，裝置確認指令的時間。

• 開始：Google 會將 action.devices.EXECUTE 要求傳送至你的完成網址。
• 測量時間範圍：雲端接收指令並傳回確認回應所花費的時間。
• 結束：Google 收到 SUCCESS、PENDING 或 OFFLINE 狀態回應。
• 技術範圍：這項指標會評估 Google Cloud 與您的雲端之間的「回應 Ack」時間。這項指標不會測量實體硬體 (例如燈泡) 完成實體狀態變更所需的時間，因為這通常涉及雲端至雲端路徑以外的本機網狀網路延遲。

縮短延遲的選項

地理位置路由的架構建議

如果無法實作任播 IP，建議採用下列經濟實惠的替代方案，確保使用者能透過最接近的區域資料中心取得服務。

1. 全球負載平衡 (GLB)

   請使用全域應用程式負載平衡器 (適用於大多數主要雲端供應商)，而非靜態路由。

   • 運作方式：您可以在網路邊緣設定單一全域進入點 (網址)，負載平衡器會自動偵測 Google 履行叢集的要求地理來源，並將流量轉送至最近的區域健康後端。

   • 優點：這項功能可提供 Anycast 的效能，但設定複雜度和成本都大幅降低。

2. 地理位置感知 DNS (GeoDNS)

   • 運作方式：設定 DNS 供應商，根據 DNS 查詢的地理位置，將完成網址解析為不同的 IP 位址。

   • 實作：請確保 DNS 供應商已針對 Google 的輸出點完成最佳化。當 Google 的區域履行服務 (例如美國、歐盟或亞洲) 解析您的網域時，會收到該特定區域資料中心的 IP 位址。

應用程式層的最佳化策略

除了基礎架構層級的路由，您還可以在應用程式層級實作下列策略，減少要求處理作業的延遲時間。

1. 「Trampoline」Proxy 方法

   如果必須維護主要資料中心，請使用區域輕量型 Proxy 伺服器 (Trampolines) 處理初始信號交換。

   1. Google 會連線至全球網址。

   2. 區域 Proxy (例如輕量型 Nginx 或 Lambda 函式) 會接收要求。

   3. Proxy 會透過內部高速骨幹將酬載轉送至主要資料庫。

   優點：這項功能可縮短「TCP 交握」時間，而這通常是長距離要求延遲的最大因素。

2. 存取權杖區域提示

   在帳戶連結 (OAuth) 程序中，系統可以識別使用者的住家區域。

   實作：將區域 ID 編碼至發給 Google 的 access_token。Google 傳送履行要求時，閘道可以立即檢查權杖，並將要求傳送至正確的區域叢集，不需要查詢資料庫。

系統健康狀態 - 合作夥伴與 Google 的指標

維持成功率 >= 99.5% 有助於確保 Google Home 中的裝置狀態正確無誤、裝置新增及移除作業順利完成、自動化動作正常觸發，以及歷史記錄事件顯示在 Google Home app (GHA) 的「活動」分頁中。

系統會根據雲端推送狀態更新時 Google 傳回的 HTTP 回應代碼，計算成功率。為確保合作夥伴不會因 Google 端的基礎架構問題而受到處罰，這項指標會從失敗次數中排除 Google 內部錯誤。計算中包含的 API 呼叫位於 HomeGraph API 參考資料中。

「成功」的定義為何？

2xx (成功)：Home Graph 已成功接收並處理狀態更新。

什麼是「失敗」？

4xx (合作夥伴錯誤) 代表失敗，並指出從雲端傳送的要求有問題。常見代碼包括：

400 錯誤的要求

原因：伺服器無法處理要求，因為語法無效。常見原因包括 JSON 格式錯誤，或是字串值使用空值而非「""」。

解決方法：確認要求主體為有效的 JSON (沒有結構錯誤或字串欄位的空值)，並驗證 agentUserId 是否與SYNC 回應中的值相符。

404 找不到網頁

原因：HomeGraph 中找不到 deviceId 或 agentUserId (尚未同步、已取消連結或 ID 不符)。

解決方法：

1. 確認 agentUserId 與SYNC 回應中提供的值相符。
2. 使用 Home Graph SYNC API，判斷 404 Not Found 錯誤是否是由於 Home Graph 中缺少裝置或使用者所致。
3. 請務必在新增、移除、重新命名或更新裝置或帳戶後，觸發 requestSync ，確保狀態保持最新。
4. 正確處理 DISCONNECT 意圖，停止回報過時的裝置。收到 DISCONNECT 意圖後，雲端服務應停止透過「要求同步」和「回報狀態」向 Google 發布變更。

429 資源用盡

原因：您的整合服務已超過配額上限。

解決方法：請參閱配額管理資訊主頁的「步驟 2a：偵錯配額問題」一節中的操作說明。您也可以參閱智慧住宅配額和限制，瞭解更多資訊。

裝置健康狀態 - 狀態準確度

狀態準確度 >= 99.5% 可確保使用者查看裝置狀態或使用「幫我找 Google Home」等 AI 功能時，看到正確的結果。如果狀態準確度偏低，自動化動作可能不會觸發，且記錄項目可能不會在正確時間顯示於「活動記錄」分頁中。GHA詳情請參閱「報告狀態」。請注意：所有支援的特徵都必須達到州別準確度目標。

1. 準確度元件

這項指標是根據「樣本」計算得出，Google 可根據已知的意圖結果驗證回報的狀態。為確保技術精確度，我們會透過兩種不同的途徑評估準確率：

• 查詢準確度：使用者或系統主動查詢裝置目前狀態時，系統會驗證準確度。
• 執行準確度：評估控制要求後回報的裝置狀態，藉此進行驗證。

2. 資訊主頁指標 (每小時計算)

資訊主頁會根據 1 小時間隔計算準確度。為確保統計信賴度，並避免因低訊號干擾而懲處整合，Google 會強制執行最低流量門檻。如果特定特徵和裝置組合在 5 天的滾動時間範圍內，累積的樣本總數少於 100 個，則其準確度會被視為統計上不顯著，並設為「不適用」。

如果兩個路徑的小時樣本量都充足，系統會計算特定狀態的每小時基準準確度，也就是兩個獨立百分比的平均值：

每小時狀態準確度 = (查詢準確度 % + 執行準確度 %) / 2

其中每個路徑的定義如下：

• 查詢準確率百分比 = (每小時查詢準確樣本) / (每小時查詢樣本總數)
• 執行準確度百分比 = (每小時執行準確樣本數) / (每小時執行總樣本數)

特徵準確率 (依特徵計算) = SUM(查詢準確樣本 + 執行準確樣本) / SUM(查詢樣本總數 + 執行樣本總數)

由於品質分數會評估整個生態系統的嚴格最低成效，因此每個支援且符合資格的特徵都必須個別達到 >= 99.5% 的狀態準確度目標 (這不是特徵的平均值)。

這個檢視畫面可防止高用量裝置的準確度極高，而掩蓋低用量裝置的準確度問題。合作夥伴不必擔心用量不足的特徵會降低分數，因為系統會自動檢查最低流量，確保用量極低的特徵不會納入最低類型和特徵分數的計算，除非該特徵達到必要的樣本門檻。

3. 提升裝置健康狀態和準確度

如果 Home Graph 儲存的狀態與即時 QUERY 的結果不符，就會發生差異。

「缺少欄位」錯誤

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

原因：發生 DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD 或 DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD 錯誤時，QUERY 回應和 Report State 要求中，同一裝置的酬載欄位集會有所不同。

解決方法：請確保兩條路徑的資料結構相同。如果 SYNC 中包含特徵，則主動式報表和被動式查詢中都必須有對應的欄位，且欄位內容一致。

「不準確」錯誤

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

原因：發生 DETAILED_ACCURACY_RESULT_INACCURATE 錯誤時，QUERY 回應中傳回的值與最後一個報表狀態值之間存在差異。

解決方法：請確保裝置狀態變更時一律會觸發 Report State，且 Report State 和 QUERY 一律會提供完全相同的最新值和所有必填欄位，以維持資料一致性。

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

原因：發生 DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE 錯誤時，合作夥伴已順利執行指令，但未將更新後的裝置狀態回報給 Google。

解決方法：執行指令後，請務必傳送「回報狀態」更新，讓 Home Graph 接收新的裝置狀態。

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

原因：發生 DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED 錯誤時，系統未收到這部裝置的 ReportState (狀態為空白，且回報的時間戳記位於紀元)，但 QUERY 結果會提供目前的狀態。這表示狀態更新未觸發、無法傳送至 HomeGraph，或是裝置無法順利回報連線或運作狀態的轉換。

解決方法：確保所有狀態變更都會觸發並成功傳送「回報狀態」。確認後端邏輯可正確處理狀態更新、向 Google HomeGraph 確認傳送成功，並確保裝置持續同步處理狀態，讓使用者介面和自動化引擎保持準確。