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% 有助於確保使用者查看裝置狀態或使用「問問智慧管家」等 AI 功能時，看到正確的結果。如果狀態準確度偏低，自動化動作可能不會觸發，且記錄項目可能不會在正確時間顯示於 GHA 的「活動記錄」分頁中。詳情請參閱「回報狀態」。

品質資訊主頁會使用「整體準確度」和「最低類型/特徵組合」這兩項指標，每小時追蹤這項資料。

1. 準確度元件

這項指標是根據「樣本」推算而來，Google 可根據已知的意圖結果驗證回報的狀態。

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

資訊主頁會根據 1 小時間隔計算準確度。如果某個小時的樣本總數少於 100 個 (S_Total < 100)，該小時的準確度會設為「不適用」。

檢視 1：整體準確度 (全球平均)

這代表整合在所有裝置類型和特徵組合中的總準確度。這項指標會提供整個生態系統的健康狀態加權平均值。

• 計算方式：所有裝置的總狀態準確度 / 所有裝置的總狀態總數。

檢視畫面 2：最低類型/特徵組合

這會找出整合中最不可靠的特定類別。這可避免高品質的大音量裝置隱藏低品質的小音量裝置。舉例來說，如果燈具的狀態準確度高於 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 (狀態為空白，且回報的時間戳記位於 Epoch 時間)，但 QUERY 結果會提供目前的狀態。這表示狀態更新未觸發、無法傳送至 HomeGraph，或是裝置無法順利回報連線或運作狀態的轉換。

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