1. 事前準備
身為物聯網 (IoT) 的開發人員,您可以打造智慧型住宅動作,讓使用者能透過 Google Home 應用程式中的觸控設定,以及搭配 Google 助理下達語音指令操控自己的裝置。
學習智慧型住宅動作的偵錯工具是與 Google 助理建構品質整合工作的重要步驟。為協助您找出並解決動作的問題,我們準備了 Google Cloud Platform (GCP) 指標、Logging 和 Test Suite for 智慧型住宅。
必要條件
- 請參閱「建立智慧型住宅動作」開發人員指南
- 執行「將智慧住宅裝置連線至 Google 助理」程式碼研究室
建構項目
在本程式碼研究室中,您將部署有 2 項瑕疵的智慧型住宅動作並連結至 Google 助理,然後透過 Test Suite 為智慧型住宅和 Google Cloud Platform (GCP) 指標和 Logging 偵錯動作的瑕疵。
課程內容
- 如何使用 GCP 指標和 Logging 找出並解決正式環境問題
- 如何使用智慧型住宅的 Test Suite 找出功能和 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 助理」程式碼研究室中內建的「動作」專案設定 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」更新 HomeGraph,使用故障程序中應用程式的最新裝置中繼資料:
開啟 Google Home 應用程式,然後確認顯示的名稱為「Faulty Washer」。
3. 測試動作
部署專案後,請測試您的動作是否控制洗衣機。
測試洗衣機
透過手機試用下列任一語音指令時,確認音量是否變更:
「Ok Google,打開洗衣機。」
「Ok Google,啟動洗衣機。」
「Ok Google,暫停使用洗衣機。」
「Ok Google,繼續處理洗衣機。」
「Ok Google,停止『洗衣』。」
當你暫停 / 恢復洗衣機時,Google 助理會透過語音回應問題:
「很抱歉,無法連線至 <專案顯示名稱>。」
如要對這項問題進行偵錯,您必須先進一步瞭解錯誤,才能找出問題的根本原因。
智慧型住宅數據分析資訊主頁
您可以前往 Smarthome Analytics 資訊主頁查看錯誤,其中匯總了您雲端執行要求的使用情形和健康狀態指標圖表:
- 「用量」指標反映智慧型住宅動作的使用情形趨勢,包括每日活躍使用者人數,以及完成要求的總要求次數。
- 「健康」指標可協助您監控智慧型住宅動作的異常情況,包括要求延遲時間、成功百分比和錯誤細目。
如要縮小錯誤原因,請按照下列步驟存取專案資訊主頁。
- 在動作控制台中,前往「專案」頁面。
- 選取智慧型住宅專案。
- 選擇「Analytics (分析)」分頁標籤,然後點選「前往 Google Cloud Platform」。
- 系統會將您導向 Google Cloud 中專案的資訊主頁清單。選取「Google Home Analytics - 雲端整合」資訊主頁。
- 向下捲動至「Cloud Fulfillment errors - Status Breakdown」圖表,查看醒目顯示時間範圍內的錯誤代碼。
PARTNER_RESPONSE_MISSING_DEVICE
錯誤代碼會提供根本原因的提示。接著,根據錯誤代碼擷取事件記錄以瞭解詳情。
存取事件記錄
如要進一步瞭解這個錯誤,請透過 Cloud Logging 存取智慧居家動作的事件記錄。
在 Google Cloud Platform 中開啟「導覽選單」,然後在「作業」下方依序選取「Logging」 >「記錄檔探索工具」,存取專案的事件記錄檔。或者,您也可以在搜尋框中搜尋「記錄檔探索工具」。
在「Query」區段中,輸入查詢 PARTNER_RESPONSE_MISSING_DEVICE
,然後按一下「Run Query」。與查詢相符的記錄會顯示在「查詢結果」部分。
錯誤記錄會顯示智慧住宅事件,並附上錯誤詳細資料:
- 使用者執行的動作為「恢復洗衣機」(
actionType:
的「STARTSTOP_UNPAUSE
」),對應最近失敗的語音指令。 - 相關聯的偵錯訊息為「
JSON response does not include device.
」
根據偵錯訊息,您應檢查洗衣機應用程式未在 EXECUTE
回應中加入正確裝置的原因。
找出錯誤的根本原因
在 functions/index.js
中,找出會傳回每個指令狀態和新裝置狀態的 EXECUTE
處理常式 (在 onExecute
陣列中)。將裝置 ID 插入 EXECUTE
回應取決於 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 Settings」步驟中,系統會顯示測試套件,並列出洗衣機的裝置類型和特徵。
- 停用「Test Request Sync」選項,因為範例應用程式沒有可新增 / 移除 / 重新命名洗衣機的 UI。在工作系統中,每當使用者新增 / 移除 / 重新命名裝置時,您都必須觸發 Request Sync。
- 點選「下一步」開始執行測試。
測試套件執行完畢之後,請查看測試案例的結果。您會發現兩筆失敗的測試案例,以及對應的錯誤訊息:
如要對智慧型住宅動作失敗進行偵錯,您需要先分析錯誤訊息來找出錯誤的根本原因。
分析錯誤訊息
為協助開發人員找出根本原因,Test Suite 會針對每個測試案例顯示錯誤訊息,說明失敗的原因。
以上方第一個失敗的測試案例來說
錯誤訊息表示測試套件預期在智慧型住宅動作回報的狀態中,預期有 "isPause": true
,但實際狀態只會包含 "isPause": false
。
此外,第二個失敗的測試案例的錯誤訊息會指出智慧型住宅動作的 QUERY
回應中,其中的狀態包含 "isPause": true
,這與智慧型住宅動作回報的狀態不同:"isPause": false
:
根據兩則錯誤訊息,您應該檢查動作回報的 isPaused
是否為正確的值。
找出錯誤的根本原因
開啟 functions/index.js
,其中包含 reportstate
函式,可透過報告狀態將狀態變更發布至 Home Graph。檢查報表狀態酬載,就會發現酬載缺少 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. 恭喜
恭喜!您已學會如何透過 Test Suite 排解智慧型住宅及 GCP 指標和記錄功能的智慧住宅動作問題。
瞭解詳情
建構本程式碼研究室後,您可以嘗試下列練習並瀏覽其他資源:
- 在裝置上新增更多支援的 traits,並使用 Test Suite 進行測試。
- 建立資訊主頁、設定快訊及透過程式輔助方式存取指標資料,取得動作的相關實用指標。
- 歡迎瀏覽適用於智慧型住宅的當地出貨服務。
- 詳情請參閱我們的 GitHub 範例。
您也可以進一步瞭解如何測試並提交動作以供審查,包括向使用者發布動作的認證程序。