1. 事前準備
本程式碼研究室專為 Google Home 合作夥伴和開發人員設計，協助他們透過雲端整合功能提升生態系統品質和使用者體驗。
課程內容
Google Home Vitals 資訊主頁是開發人員和合作夥伴監控 Google Home 整合運作狀態的單一資料來源。在使用者體驗取決於延遲和穩定性的生態系統中，Google Home Vitals 是自助式入口網站，提供所有深入分析資料，協助您從被動式疑難排解轉為主動式品質管理。
- 品質整合分數的計算方式
- 如何解讀及使用資訊主頁
- 如何偵錯品質指標不佳的問題
軟硬體需求
- 擁有 Google Home Cloud Integration
設定
如何前往 Google Home Vitals 資訊主頁：
2. 如何解讀資訊主頁
品質分數計算 -「良好」與「不佳」標準
資訊主頁會顯示品質分數的細目。系統會根據裝置類型精細程度指派品質分數。如要讓裝置類型整合達到「良好」等級，必須同時符合四項條件：
- 全球成功率：合作夥伴對 Google 的整體呼叫成功率必須高於或等於 99.5%。
注意：如果全球成功率未達標準 (高於或等於 99.5%)，無論個別裝置效能如何，整個專案都會自動獲得「不佳」評分。 - 指令可靠性：每種裝置類型的 QUERY 和 EXECUTE 成功率都必須 >=99.5%。
- 回應延遲時間：每種裝置類型的 QUERY 和 EXECUTE 第 90 百分位延遲時間必須 <=1000 毫秒。
- 狀態完整性：狀態準確度必須高於或等於 99.5%。
這些指標的重要性
- 全球成功率：合作夥伴對 Google 的呼叫 (整合層級) 會評估從雲端到 Google 的呼叫是否正常。成功率 >= 99.5% 可確保 Google Home 使用正確的裝置狀態。例如，確認裝置已新增及移除、自動化動作已觸發，以及歷史記錄事件顯示在 Google Home 應用程式的「活動記錄」分頁中。
- 指令可靠性：系統會以裝置類型為單位，測量 QUERY 和 EXECUTE 的成功率。成功率達到 99.5% 以上，可確保使用者指令正確執行 (即避免出現「我無法連上裝置」等 Google 助理回覆，或錯誤確認未執行的指令)。
- 回應延遲：系統也會在裝置類型層級測量 QUERY 和 EXECUTE 延遲，確保每種裝置類型的延遲時間 <=1000 毫秒，讓使用者不必等待太久就能執行所需動作 (例如等待幾秒讓燈光關閉)。
- 狀態完整性：狀態準確度：評估 Google 系統儲存的狀態準確度，以及用於提供使用者查詢結果的狀態。如果這些數字偏低，使用者在查看裝置狀態或使用「問問智慧管家」等 AI 功能時，可能會看到不正確的結果。自動化動作可能無法觸發，活動記錄中也可能不會顯示正確時間的記錄項目。
如何解讀資訊主頁
首先請查看「品質分數指標」部分，這是整合的主要健康指標。如要獲得「良好」裝置等級評分，本節中的所有指標都必須符合「綠色」成功條件。如需詳細技術規定和指標定義，請參閱Developer Center 說明文件。
Google Home Vitals 資訊主頁頂端的「品質指標分數」部分，會顯示用於計算整合品質分數的指標。
圖例
- 綠色 (良好)：指標符合品質門檻。
- 紅色 (不佳)：指標未達品質門檻。
範例
在下方範例中，您可以看到 AC_UNIT 裝置類型符合「查詢」和「執行」成功率以及「查詢延遲時間」部分的品質條件，但「執行延遲時間」部分未達標準 (紅色)。這表示指令的通過率符合標準，但 EXECUTE 延遲時間慢了 36 毫秒。「系統健康狀態」部分顯示整合中匯總方法的失敗率為 98.92%，表示還有改善空間，確保 Google Home 裝置狀態的準確度。這表示有 1.08% 的呼叫 (DeleteAgentUser、Query、ReportStateAndNotification、RequestSyncDevices 或 Sync) 傳回的回應代碼不等於 2xx 或 5xx (例如 404 錯誤)。用來評估 AC_UNIT 裝置類型通過/失敗品質的最後一個指標是狀態準確度。在這個範例中，成功率為 77.43%，表示使用者看到的裝置結果可能不準確。根據這三項指標，AC_UNIT 的整體分數為「不佳」，低於品質門檻。
以下每個品質計算結果都對應到下方的偵錯章節。展開摺疊步驟，進一步偵錯。
如要偵錯 QUERY/EXECUTE 成功率和延遲時間，請前往「步驟 1：驗證雲端呼叫」。
如要偵錯合作夥伴至 Google 的成功率，請前往「步驟 2：驗證對 Google 的呼叫」。
如要針對各裝置類型偵錯狀態準確度，請前往「步驟 3：提高狀態準確度」。
3. 偵錯步驟 1：驗證 Cloud Call
步驟 1：總覽
本節著重於雲端通話，也就是用來評估 Google 與雲端後端通訊狀況的指標 (也稱為 Google 對合作夥伴指標)。包括「Query」(查詢)、「Execute」(執行) 等指令。
我們會追蹤 QUERY 和 EXECUTE 的成功率和延遲時間 (這會影響裝置類型品質分數)。
下方的總覽畫面會顯示整合層級的 QUERY、EXECUTE 成功率和錯誤。步驟 1a 至 1d 顯示裝置類型/特徵層級的這些指標細目。
步驟 1a 和 1b 會顯示一段時間內的履行要求數量趨勢、錯誤數量和特定錯誤狀態。
步驟 1a：查看查詢錯誤
步驟 1b：查看執行錯誤
步驟 1c 和 1d 會顯示這些指標的第 90 和第 50 個百分位數，並依整合層級和裝置類型層級細分。
步驟 1c：查看查詢延遲時間
步驟 1d：查看執行延遲時間
4. 偵錯步驟 2：驗證對 Google 的呼叫
步驟 2：總覽
完成從 Google 到合作夥伴的呼叫偵錯後，第二個步驟是偵錯從合作夥伴雲端到 Google 的呼叫。本節涵蓋合作夥伴整合層級的指標，而非裝置類型層級的指標，包括 400 Bad Request、404 Not Found 和 429 Resource Exhausted 等回應代碼。
步驟 2a：偵錯配額問題
Google Home 對於資源的分配與使用設有一定的限制，並且會根據每個專案的狀況來調整可用的配額。Google 會對查詢、刪除、報表狀態和非同步要求同步 API 呼叫的匯總，套用每 60 秒 6,000 個要求的預設限制，並以雲端對雲端整合為單位。
達到配額上限可能會導致狀態更新失敗，進而造成不符，對報表狀態準確度造成負面影響。以下圖表會顯示報表狀態和要求同步處理錯誤的細目，以及 API 方法的計數和錯誤細目，以及配額用量百分比。如果這些圖表顯示流量異常增加，請檢查整合功能，判斷是否有變更導致更多流量傳送至 Home Graph API。
在某些情況下，例如流量隨時間自然成長 (例如成長與裝置數量增加、推出新裝置類型或其他預期推出內容一致)，增加整合的配額可能合適。如要申請提高配額，請按照開發人員說明文件的步驟操作。
5. 偵錯步驟 3：提高狀態準確度
步驟 3：總覽
完成步驟 1 和步驟 2 的偵錯後，步驟 3 會涵蓋「回報狀態」的準確度。回報狀態是指儲存在 Google 系統中的裝置狀態，用於處理使用者查詢。依特徵和裝置類型細分的資料如下所示。步驟 3a 和 3b 涵蓋「回報狀態」的兩種常見錯誤：缺少欄位錯誤和不準確錯誤。
步驟 3a：「缺少欄位」錯誤
如果特定裝置的 QUERY 回應和回報狀態要求之間，酬載欄位集有所不同，就會導致「缺少欄位」錯誤。每部裝置酬載中的欄位組合必須相同。如果酬載的計算邏輯在 QUERY 和報表狀態回應之間有所不同，就可能導致這種情況。請參閱下方的圖表，追蹤哪些裝置類型和特徵的 QUERY 和回報狀態回應不相符。
步驟 3b：「不準確」錯誤
如果特定裝置的 QUERY 回應和回報狀態要求具有相同的酬載欄位集，但狀態值不同，就會導致不準確的錯誤。如果缺少狀態報表，或是 QUERY 和狀態報表的狀態計算邏輯不同，就可能發生這種情況。請參閱下方的圖表，追蹤哪些裝置類型和特徵的 QUERY 和回報狀態回應不相符。
6. 其他說明文件和資源
- 如要提供意見回饋或回報這個資訊主頁的問題，請在公開的 Issue Tracker 中回報問題。
- 如要提出申訴要求，請使用品質指標申訴表單提出問題。
- 如要定期掌握整合品質，請設定 Google Cloud Platform 快訊，在指標低於可接受的門檻時收到通知。確保您在發生問題時，能第一時間收到通知。
- 如需其他資訊，請參閱開發人員說明文件：https://developers.home.google.com/tools/analytics/home-vitals