如要支援本機執行要求,您必須建構可處理這些智慧型住宅意圖的應用程式:
IDENTIFY
:支援尋找本機可控制的智慧型裝置。意圖處理常式會擷取智慧型裝置在探索期間傳回的資料,並透過回應傳送給 Google。EXECUTE
:支援執行指令。QUERY
:支援查詢裝置狀態。REACHABLE_DEVICES
:(非必要) 支援探索中樞裝置 (或橋接) 裝置背後的本機可控制最終裝置。
這個應用程式會在使用者的 Google Home 或 Google Nest 裝置上執行,並將智慧型裝置連結至 Google 助理。您可以使用 TypeScript (建議) 或 JavaScript 建立應用程式。
建議您使用 TypeScript,因為您可以透過繫結靜態確保應用程式傳回的資料符合平台預期的類型。
如要進一步瞭解這個 API,請參閱 Local Home SDK API 參考資料。
下列程式碼片段說明如何初始化本機執行要求應用程式,並附加處理常式。
import App = smarthome.App; const localHomeApp: App = new App("1.0.0"); localHomeApp .onIdentify(identifyHandler) .onExecute(executeHandler) .listen() .then(() => { console.log("Ready"); });
import App = smarthome.App; const localHomeApp: App = new App("1.0.0"); localHomeApp .onIdentify(identifyHandler) .onReachableDevices(reachableDevicesHandler) .onExecute(executeHandler) .listen() .then(() => { console.log("Ready"); });
建立專案
為了部署本機執行要求應用程式,您必須為程式碼及其所有依附元件建構 JavaScript 套件。
使用本機執行要求應用程式專案初始化器,透過您偏好的 Bundler 設定啟動適當的專案結構。
專案範本
如要選取 Bundler 設定,請執行 npm init
指令,如下列範例所示:
不含 Bundler 設定的 TypeScript:
npm init @google/local-home-app project-directory/ --bundler none
專案架構:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json └── serve.js
將 project-directory 替換為將包含本機執行要求應用程式專案的新目錄。
具備 webpack 套裝組合設定的 TypeScript:
npm init @google/local-home-app project-directory/ --bundler webpack
專案架構:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json ├── webpack.config.web.js ├── webpack.config.node.js └── serve.js
將 project-directory 替換為將包含本機執行要求應用程式專案的新目錄。
具有匯總組合器設定的 TypeScript:
npm init @google/local-home-app project-directory/ --bundler rollup
專案架構:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json ├── rollup.config.js └── serve.js
將 project-directory 替換為將包含本機執行要求應用程式專案的新目錄。
具有 Parcel 套裝組合設定的 TypeScript:
npm init @google/local-home-app project-directory/ --bundler parcel
專案架構:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json └── serve.js
將 project-directory 替換為將包含本機執行要求應用程式專案的新目錄。
執行常見的專案層級工作
產生的專案支援下列 npm 指令碼:
cd project-directory/ npm run build
這個指令碼會編譯 TypeScript 來源,並將應用程式及其依附元件封裝到 Chrome 執行階段環境位於 dist/web
子目錄中,以及 dist/node
子目錄中的 Node.js 執行階段環境。
cd project-directory/ npm run lint npm run compile npm test
這個指令碼會驗證 TypeScript 程式碼的語法,編譯程式碼時不會在 dist/
子目錄中產生任何輸出內容,並透過 test.ts
執行自動化測試。
cd project-directory/ npm run start
在開發期間,這個指令碼會在本機提供適用於 Chrome 和 Node.js 執行階段環境的應用程式套件。
實作 IDENTIFY 處理常式
當 Google Home 或 Google Nest 裝置重新啟動並查看未經驗證的本機裝置 (包括連結至中樞裝置的端點) 時,系統會觸發 IDENTIFY
處理常式。Local Home 平台會使用您之前指定的掃描設定資訊來掃描本機裝置,並根據掃描結果呼叫 IDENTIFY
處理常式。
本地首頁平台的 IdentifyRequest
包含 LocalIdentifiedDevice
執行個體的掃描資料。根據發現裝置的掃描設定,系統只會填入一個 device
執行個體。
如果掃描結果與裝置相符,IDENTIFY
處理常式應傳回 IdentifyResponsePayload
物件,其中包含具有智慧型住宅中繼資料的 device
物件 (例如類型、特徵和報告狀態)。
如果 IDENTIFY
回應的 verificationId
與 SYNC
回應傳回的其中一個 otherDeviceIds
值相符,Google 就會建立裝置關聯。
範例
下列程式碼片段說明如何為獨立裝置和中樞整合建立 IDENTIFY
處理常式。
const identifyHandler = (request: IntentFlow.IdentifyRequest): IntentFlow.IdentifyResponse => { // Obtain scan data from protocol defined in your scan config const device = request.inputs[0].payload.device; if (device.udpScanData === undefined) { throw Error("Missing discovery response"); } const scanData = device.udpScanData.data; // Decode scan data to obtain metadata about local device const verificationId = "local-device-id"; // Return a response const response: IntentFlow.IdentifyResponse = { intent: Intents.IDENTIFY, requestId: request.requestId, payload: { device: { id: device.id || "", verificationId, // Must match otherDeviceIds in SYNC response }, }, }; return response; };
const identifyHandler = (request: IntentFlow.IdentifyRequest): IntentFlow.IdentifyResponse => { // Obtain scan data from protocol defined in your scan config const device = request.inputs[0].payload.device; if (device.udpScanData === undefined) { throw Error("Missing discovery response"); } const scanData = device.udpScanData.data; // Decode scan data to obtain metadata about local device const proxyDeviceId = "local-hub-id"; // Return a response const response: IntentFlow.IdentifyResponse = { intent: Intents.IDENTIFY, requestId: request.requestId, payload: { device: { id: proxyDeviceId, isProxy: true, // Device can control other local devices isLocalOnly: true, // Device not present in `SYNC` response }, }, }; return response; };
識別中樞裝置背後的裝置
如果 Google 辨識出中樞裝置,就會將中樞裝置視為中樞的已連結終端裝置,並嘗試驗證這些裝置。
如要讓 Google 確認有中樞裝置存在,請按照 IDENTIFY
處理常式的操作說明進行:
- 如果
SYNC
回應回報已連結至中心的本機裝置 ID,請在IdentifyResponsePayload
中將isProxy
設為true
。 - 如果
SYNC
回應未回報中樞裝置,請在IdentifyResponsePayload
中將isLocalOnly
設為true
。 device.id
欄位包含中樞裝置本身的本機裝置 ID。
實作 REACHABLE_裝置處理常式 (僅限中樞整合)
Google 會傳送 REACHABLE_DEVICES
意圖,以確認哪些裝置可以透過本機控制。只要 Google 偵測到中心連線已上線,每次 Google 執行探索掃描 (大約每分鐘一次) 時,就會觸發這個意圖。
實作 REACHABLE_DEVICES
處理常式的方式與 IDENTIFY
處理常式類似,但處理常式需要收集本機 Proxy (亦即中樞) 裝置可存取的其他裝置 ID。device.verificationId
欄位包含連結至中樞裝置的終端裝置本機裝置 ID。
本地首頁平台的 ReachableDevicesRequest
包含 LocalIdentifiedDevice
的執行個體。透過這個執行個體,您可以取得 Proxy 裝置 ID 以及掃描結果的資料。
REACHABLE_DEVICES
處理常式應會傳回 ReachableDevicesPayload
物件,其中包含的 devices
物件,該物件包含 verificationId
值的陣列,代表中樞所控制的結束裝置。verificationId
值必須與 SYNC
回應中的其中一個 otherDeviceIds
相符。
下列程式碼片段說明如何建立 REACHABLE_DEVICES
處理常式。
const reachableDevicesHandler = (request: IntentFlow.ReachableDevicesRequest): IntentFlow.ReachableDevicesResponse => { // Reference to the local proxy device const proxyDeviceId = request.inputs[0].payload.device.id; // Gather additional device ids reachable by local proxy device // ... const reachableDevices = [ // Each verificationId must match one of the otherDeviceIds // in the SYNC response { verificationId: "local-device-id-1" }, { verificationId: "local-device-id-2" }, ]; // Return a response const response: IntentFlow.ReachableDevicesResponse = { intent: Intents.REACHABLE_DEVICES, requestId: request.requestId, payload: { devices: reachableDevices, }, }; return response; };
實作 EXECUTE 處理常式
應用程式中的 EXECUTE
處理常式會處理使用者指令,並透過 Local Home SDK 透過現有通訊協定存取智慧型裝置。
Local Home 平台會將與 EXECUTE
意圖的相同輸入酬載傳遞至 EXECUTE
處理常式函式,與 Cloud 執行要求相同。同樣地,EXECUTE
處理常式會傳回與處理 EXECUTE
意圖相同的格式輸出資料。如要簡化回應建立程序,您可以使用 Local Home SDK 提供的 Execute.Response.Builder
類別。
您的應用程式無法直接存取裝置的 IP 位址。請改用 CommandRequest
介面,根據以下其中一種通訊協定建立指令:UDP、TCP 或 HTTP。然後呼叫 deviceManager.send()
函式來傳送指令。
對裝置指定指令時,請使用 SYNC
回應中的裝置 ID (以及 customData
欄位的參數 (如有)) 來與裝置通訊。
範例
下列程式碼片段說明如何建立 EXECUTE
處理常式。
const executeHandler = (request: IntentFlow.ExecuteRequest): Promise<IntentFlow.ExecuteResponse> => { // Extract command(s) and device target(s) from request const command = request.inputs[0].payload.commands[0]; const execution = command.execution[0]; const response = new Execute.Response.Builder() .setRequestId(request.requestId); const result = command.devices.map((device) => { // Target id of the device provided in the SYNC response const deviceId = device.id; // Metadata for the device provided in the SYNC response // Use customData to provide additional required execution parameters const customData: any = device.customData; // Convert execution command into payload for local device let devicePayload: string; // ... // Construct a local device command over TCP const deviceCommand = new DataFlow.TcpRequestData(); deviceCommand.requestId = request.requestId; deviceCommand.deviceId = deviceId; deviceCommand.data = devicePayload; deviceCommand.port = customData.port; deviceCommand.operation = Constants.TcpOperation.WRITE; // Send command to the local device return localHomeApp.getDeviceManager() .send(deviceCommand) .then((result) => { response.setSuccessState(result.deviceId, state); }) .catch((err: IntentFlow.HandlerError) => { err.errorCode = err.errorCode || IntentFlow.ErrorCode.INVALID_REQUEST; response.setErrorState(device.id, err.errorCode); }); }); // Respond once all commands complete return Promise.all(result) .then(() => response.build()); };
實作 QUERY 處理常式
應用程式中的 QUERY
處理常式會處理使用者要求,並使用 Local Home SDK 回報智慧型裝置的狀態。
Local Home 平台會將與 QUERY
意圖的相同要求酬載傳遞至「QUERY」處理常式函式,同樣地,QUERY
處理常式會傳回資料,其格式與處理 QUERY
意圖時相同。
將指令傳送至中樞裝置後方的裝置
如要控制中樞裝置後方的最終裝置,您可能需要在傳送至中樞的通訊協定專屬指令酬載中提供額外資訊,以便中樞識別指令的目標裝置。在某些情況下,您可以直接從 device.id
值推斷出這項資訊,但如果這不是情況,您應該在 customData
欄位中納入這項額外資料。
如果您是使用 TypeScript 建立應用程式,請記得將應用程式編譯為 JavaScript。您可以使用自己選擇的模組系統編寫程式碼。確認 Chrome 瀏覽器支援您的目標。