本頁面由 Cloud Translation API 翻譯而成。

偵錯智慧型住宅

1. 事前準備

物聯網 (IoT) 開發人員可以打造智慧型住宅動作，讓使用者能夠透過 Google Home 應用程式的觸控設定和 Google 助理語音指令來控制裝置。

要瞭解與 Google 助理整合的生產品質整合作業，你必須瞭解智慧型住宅動作的偵錯工具。為了方便監控及偵錯，Google Cloud Platform (GCP) 指標、Logging 和 Smart Home for Smart Home 可協助您找出並解決動作的問題。

必要條件

閱讀建立智慧型住宅動作開發人員指南
執行將智慧住宅裝置連線到 Google 助理程式碼研究室

建構項目

在本程式碼研究室中，您將部署包含 2 個瑕疵的智慧型住宅動作，並將該動作與 Google 助理建立連結，然後透過測試套件對智慧型住宅和 Google Cloud Platform (GCP) 指標和 Logging 的瑕疵進行偵錯。

課程內容

如何使用 GCP 指標和 Logging 找出並解決實際工作環境的問題
如何使用智慧型住宅的測試套件來找出功能性與 API 的問題

軟硬體需求

使用 Google Chrome 等網路瀏覽器
已安裝 Google Home 應用程式的 iOS 或 Android 裝置
Node.js 10.16 以上版本
Google Cloud 帳單帳戶

2. 執行錯誤的應用程式

取得原始碼

點選下列連結，在開發機器下載本程式碼研究室的範例：

...您也可以透過指令列複製 GitHub 存放區：

$ git clone https://github.com/google-home/smarthome-debug.git

關於專案

洗衣機應用程式包含下列子目錄：

public：前端 UI，可讓您輕鬆控制和監控智慧型洗衣機的狀態。
functions：完全實作的雲端服務，透過 Cloud Functions for Firebase 和 Firebase 即時資料庫管理智慧型洗衣機。

連結至 Firebase

在您的開發機器上開啟終端機。前往 washer-faulty 目錄，然後透過將智慧住宅裝置連結至 Google 助理程式碼研究室內建的 Actions 專案設定 Firebase CLI：

$ cd washer-faulty
$ firebase use <project-id>

部署至 Firebase

前往 functions 資料夾，然後使用 npm. 安裝所有必要的依附元件

$ cd functions
$ npm install

注意：如果看到以下訊息，請忽略該訊息，然後繼續下一步。這項警告是因為部分較舊的依附元件所導致。詳情請參閱這篇文章。

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

現在您已安裝依附元件並設定專案，可以開始部署錯誤的洗衣機應用程式。

$ firebase deploy

以下是您應該會看到的主控台輸出結果：

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<project-id>.firebaseapp.com

更新 HomeGraph

在瀏覽器中開啟 Hosting URL (檢視網址，https://<project-id>.firebaseapp.com) 以查看網路應用程式。在網頁 UI 中，按一下 [Refresh] (重新整理) 按鈕，即可透過 Request Sync 更新錯誤 - 以執行錯誤洗衣機應用程式的最新裝置中繼資料：

開啟 Google Home 應用程式，然後確認名稱為「Faulty Washer」的洗衣機裝置。

3. 測試動作

部署專案之後，請測試您的動作是否能控制洗衣機。

測試洗衣機

嘗試在手機上透過以下任一種語音指令來檢查數值是否正確：

「Ok Google，打開洗衣機。」

「Ok Google，啟動洗衣機。」

「Ok Google，暫停洗衣機。」

「Ok Google，繼續洗碗機。」

「Ok Google，停止洗手。」

當你暫停 / 繼續洗碗機時，Google 助理會回應語音回應錯誤：

「很抱歉，我無法連線至 <專案顯示名稱>。」

如要對這類問題進行偵錯，您必須先取得關於錯誤資訊，才能找出問題範圍及找出根本原因。

智慧型住宅數據分析資訊主頁

查看錯誤是智慧型住宅 Analytics (分析) 資訊主頁的好幫手。這個資訊主頁可匯總您雲端執行項目的使用情況和健康指標圖表：

「用量」指標會顯示智慧住宅動作的使用情況趨勢，包括每日活躍使用者人數和出貨要求總數。
健康指標可協助您監控智慧型住宅動作的異常狀況，包括要求延遲、成功百分比和錯誤細目。

請按照下列步驟存取專案資訊主頁，以縮小錯誤原因。

在動作控制台中，前往「專案」頁面。
選取你的智慧型住宅專案。
選擇 [Analytics (分析)] 標籤，然後按一下 [前往 Google Cloud Platform]。

系統隨即會將您導向 Google Cloud 中專案的資訊主頁清單。選取「Google Home Analytics - Cloud Integration」資訊主頁。

向下捲動至「Cloud Fulfillment Error - Status Breakdown」(Cloud 履行要求 - 狀態明細) 圖表，即可查看醒目顯示時間範圍的錯誤代碼。

PARTNER_RESPONSE_MISSING_DEVICE 錯誤代碼會提供根本原因的提示。接下來，根據錯誤代碼擷取事件記錄，以獲取更多詳細資訊。

存取事件記錄

如要進一步瞭解這項錯誤，請透過 Cloud Logging 存取智慧住宅動作的事件記錄。

在 Google Cloud Platform 中開啟「導覽選單」，然後依序選取「作業」>「Logging 記錄」>「Logs Explorer」，存取專案的事件記錄。或者，您也可以搜尋 Logs Explorer。

在「Query」(查詢) 區段中輸入查詢 PARTNER_RESPONSE_MISSING_DEVICE，然後按一下「Run Query」(執行查詢)。「Query results」(查詢結果) 部分中會顯示與查詢相符的記錄。

錯誤記錄會顯示智慧住宅事件，並附上下列詳細資料：

使用者執行的操作為「繼續播放洗衣機」(actionType:「STARTSTOP_UNPAUSE」)，與最近失敗的語音指令對應。
相關的偵錯訊息為「JSON response does not include device.」

根據偵錯訊息，您應該瞭解洗衣機應用程式未在 EXECUTE 回應中加入正確的裝置的原因。

找出錯誤的根本原因

在 functions/index.js 中，找出會傳回每個指令狀態和新裝置狀態的 EXECUTE 處理常式 (位於 onExecute 陣列中)。在 EXECUTE 回應中插入裝置 ID 取決於解析 updateDevice 函式：

index.js

app.onExecute(async (body) => {
 ...

 for (const command of intent.payload.commands) {
   for (const device of command.devices) {
     for (const execution of command.execution) {
       executePromises.push(
           updateDevice(execution, device.id)
               .then((data) => {
                 result.ids.push(device.id);
                 Object.assign(result.states, data);
               })
               .catch((e) =>
                 functions.logger.error('EXECUTE',
                     device.id, e.message)));
     }
   }
 }

進一步檢查 updateDevice 函式如何處理洗衣機的暫停 / 繼續作業，且與暫停 / 繼續指令相符的字串有誤：

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpausePause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

修正錯誤

現在已經找出錯誤的根本原因，可以修正暫停 / 恢復指令的字串：

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

測試修正結果

使用 Firebase CLI 部署更新後的程式碼：

firebase deploy --only functions

請重試下列語音指令，並在你暫停 / 繼續洗衣機時，Google 助理就能正確回應。

「Ok Google，暫停洗衣機。」

「好的，暫停洗碗機。」

「Ok Google，繼續洗手。」

「我知道了，繼續洗洗衣機。」

你也可以提問來測試洗衣機目前的狀態。

「Ok Google，我的洗手時間了嗎？」

「Ok Google，我的洗衣機正在運轉嗎？」

「Ok Google，洗衣機在我的生理週期如何？」

4. 使用測試套件測試動作

除了手動測試外，您還可以透過自動化的智慧型住宅測試套件，根據與動作相關的裝置類型和特性驗證用途。「測試套件」會執行一系列測試來偵測您的「動作」，並在發生這類事件時，顯示測試失敗訊息以協助您加快偵錯速度，再深入探討事件記錄。

執行智慧型住宅測試套件

請按照以下測試套件測試智慧型住宅動作的執行方式：

在網路瀏覽器中開啟智慧型住宅測試套件。
使用右上角的按鈕登入 Google。讓「測試套件」可將指令直接傳送至「Google 助理」。
在 [專案 ID] 欄位中，輸入智慧住宅動作的專案 ID。然後點選 [下一步] 繼續。
在「測試設定」步驟中，您會看到「測試套件」列出洗衣機的裝置類型和特性。

停用 [Test Request Sync] 選項，因為範例洗衣機應用程式沒有可新增 / 移除 / 重新命名洗衣機的 UI。在正式版系統中，每當使用者新增 / 移除 / 重新命名裝置時，您都必須觸發 Request Sync。
點選 [下一步] 即可開始執行測試。

測試套件執行完畢後，請查看測試案例結果。您會看到兩個失敗的測試案例，以及下列錯誤訊息：

如要對智慧型住宅動作執行失敗偵錯，您必須先找出錯誤的根本原因，才能找出錯誤的根本原因。

分析錯誤訊息

為協助開發人員找出問題的根本原因，測試套件會針對所有失敗的測試案例顯示錯誤訊息，說明失敗的原因。

對於上方第一個失敗的測試案例，

錯誤訊息，表示測試套件預期在智慧型住宅動作回報的狀態下"isPause": true，實際狀態卻只包含 "isPause": false。

此外，在第二個測試案例的錯誤訊息中，指出您的智慧住宅動作在「QUERY」回應中的狀態含有「"isPause": true」，這與「智慧型住宅動作」回報的狀態不同："isPause": false

根據這兩個錯誤訊息，您應該檢查動作回報的狀態是否為 isPaused。

找出錯誤的根本原因

開啟 functions/index.js，其中包含 reportstate 函式，可透過報表狀態將狀態變更發布至主圖。檢查報表狀態酬載，且該酬載缺少 isPaused 狀態，這就是測試套件在失敗測試案例中檢查的項目。

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      ...
    });

修正錯誤

找出造成問題的根本原因後，請將 isPaused 狀態加入報表狀態酬載中，藉此修改 functions/index.js：

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

測試修正結果

使用 Firebase CLI 部署更新後的程式碼：

$ firebase deploy --only functions

重新執行智慧型住宅測試套件，您會發現所有測試案例都已通過。

5. 恭喜

恭喜！您已成功透過智慧型住宅和 GCP 指標與記錄測試套件，排解智慧型住宅動作相關問題。

瞭解詳情

以本程式碼研究室為基礎，請嘗試以下練習並探索其他資源：

為您的裝置新增更多支援的特性，並使用測試套件進行測試。
建立資訊主頁、設定快訊及透過程式存取指標資料，取得與動作相關的實用使用指標。
探索智慧型住宅的本地交車選項。
請查看我們的 GitHub 範例。

您也可以進一步瞭解如何測試並提交審核動作，包括向使用者發布動作的認證程序。