Google Home Vitals (Cloud)

這套資訊主頁和警示可協助你主動維護與 Google Home 生態系統的高品質整合。Google 致力於協助合作夥伴為所有客戶打造優質生態系統。

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

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

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

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

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

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

前往資訊主頁

Google 到合作夥伴指標

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

「同步成功率 >= 99.5%」指標會評估同步要求正確執行的頻率，確保 Google Home 顯示的裝置與連線至雲端基礎架構的裝置保持同步。

「成功」的定義為何？

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

如果回應包含非封鎖例外狀況 (例如 SUCCESS 狀態伴隨 lowBattery 例外狀況)，則會視為成功交易。指令已傳送到裝置，且意圖已達成，但出現警告。

「失敗」的定義為何？

在常見平台錯誤代碼中，標示為「Partner Actionable」的錯誤，在計算 QUERY、EXECUTE 和 SYNC 成功率時，會視為「失敗」。此外，在「錯誤和例外狀況」中找到的錯誤也屬於「失敗」，但有以下例外狀況：

執行回應狀態一致性

在 EXECUTE 回應中傳回 SUCCESS 狀態時，回應酬載的 states 物件必須包含執行特徵定義的所有有效和更新狀態欄位。如果省略必要的狀態欄位，或針對複雜特徵傳回空白的 states 物件，Google Home 平台將無法剖析執行結果，並將其註冊為 AGENT_ISSUE 或 INVALID_RESPONSE 失敗，進而降低查詢和執行成功率。

「查詢/執行延遲時間 (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 雲端與您的雲端之間的「回應確認」時間。這項指標不會測量實體硬體 (例如燈泡) 完成實體狀態變更所需的時間，因為這通常涉及雲端對雲端路徑以外的區域網狀網路延遲時間。

EXECUTE/QUERY 延遲時間軸細目

分析 EXECUTE 或 QUERY 延遲時間的時間戳記時，總封包往返時間可以細分為下列依序流程：

由於這項細目會比較 Google 端和合作夥伴端的時間戳記，因此合作夥伴伺服器必須與 NTP (網路時間通訊協定) 同步。即使是微小的時鐘漂移 (50 至 100 毫秒)，也會扭曲計算出的運送時間 (t2 - t1 和 t4 - t3)，可能導致邏輯上不可能出現的指標，例如負運送延遲時間。

[t1] Request Sent (Google Outbound)：Google 提出意圖要求。由於 t1 不會直接公開，因此會從最終傳入時間戳記中減去總延遲時間，以大約計算出該值。

網路傳輸 (t1 至 t2)：預估網路傳輸和佇列時間，直到到達執行端點。

[t2] Request Received (Partner Ingress)：要求抵達環境 API Gateway 或 Ingress 伺服器的確切時間戳記。

合作夥伴處理 (t2 至 t3)：完全在雲端環境中執行的內部執行、轉送和裝置處理延遲時間。

[t3] Response Sent (Partner Egress)：服務將執行回應傳回 Google 的時間戳記。

回程傳輸 (t3 至 t4)：回程網路轉送和連線完成時間 (回到 Google)。

[t4] 要求完成 (Google 傳入)：Google 收到並處理最終回應。這個時間戳記會明確記錄在 Google Cloud 記錄中，顯示為 receiveTimestamp。

為說明這些指標之間的關聯，請考慮一個範例 EXECUTE 要求，其記錄的總延遲時間 (latencyMsec) 為 1700 毫秒，Google Cloud receiveTimestamp (t4) 為 2026-05-25T15:25:00.550Z。

縮短延遲時間的選項

地理位置轉送架構建議

如果無法導入任意傳播 IP，建議採用下列符合成本效益的替代方案，確保使用者由最近的區域資料中心提供服務。

1. 全球負載平衡 (GLB)

   請改用全域應用程式負載平衡器 (大多數主要雲端服務供應商都有提供)，而非靜態轉送。

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

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

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

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

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

應用程式層的最佳化策略

除了基礎架構層級的轉送，您也可以在應用程式層實作下列策略，縮短處理要求時的延遲時間。

1. 「Trampoline」Proxy 方法

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

   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 Bad Request

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

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

找不到 404

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

解決方法：

1. 確認 agentUserId 與同步回應中提供的值相符。
2. 使用 Home Graph SYNC API，判斷 404 找不到網頁錯誤是否因 HomeGraph 中缺少裝置或使用者而造成。
3. 請務必在新增、移除、重新命名或更新裝置或帳戶後觸發 requestSync，確保狀態保持最新。
4. 妥善處理 DISCONNECT 意圖，停止回報過時裝置。收到 DISCONNECT 意圖後，雲端服務應停止使用 Request Sync 和 Report State 將變更發布至 Google。

429 資源已用盡

原因：整合服務已超過分配的配額。

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

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

狀態準確度 >= 99.5%，可確保使用者查看裝置狀態或使用「問問智慧管家」等 AI 功能時，能看到正確的結果。如果狀態準確度偏低，自動化動作可能不會啟動，記錄項目也可能不會在適當時間顯示在 GHA 的「活動記錄」分頁中。詳情請參閱「回報狀態」。請注意：所有支援的特徵都必須達到狀態準確度目標。

1. 準確度元件

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

• 以查詢為基礎的準確度：使用者或系統主動查詢裝置目前狀態時，會驗證這項指標。
• 以 EXECUTE 為基礎的準確度：在控制要求後，評估回報的指令後裝置狀態，藉此驗證。

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，且 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。

解決方案：請務必在執行指令後傳送 Report State 更新，讓 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 錯誤表示系統未收到這部裝置的回報狀態 (狀態為空白，回報的時間戳記為 epoch)，但 QUERY 結果提供了目前狀態。這表示狀態更新未觸發、無法傳送至 HomeGraph，或裝置無法成功回報連線或運作狀態的轉換。

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