action.devices.EXECUTE
這項意圖會要求在智慧型住宅裝置上執行指令。
執行要求應處理每個指令,將指令傳輸到對應的裝置,並在 EXECUTE
回應中傳回新狀態。
單一 EXECUTE
意圖可以透過多個指令指定多部裝置。例如,觸發的意圖可在一組光源中同時設定亮度和色彩,或是將個別光源設為不同顏色。
詳情請參閱「查詢」和「執行」。
要求格式
欄位 | 類型 | 說明 |
---|---|---|
requestId |
String |
必填。 要求的 ID。 |
inputs |
陣列 |
必填。 與意圖要求相符的輸入清單。 |
[item, ...] |
物件 |
與意圖要求相關聯的類型和酬載。 |
intent |
必填。 (常數值: 意圖要求類型。 |
|
payload |
物件 |
必填。 EXECUTE 要求酬載。 |
commands |
陣列 |
必填。 裝置目標和指令組合清單。 |
[item, ...] |
物件 |
要在所連接裝置目標執行的指令集。 |
devices |
陣列 |
必填。 目標裝置清單。 |
[item, ...] |
物件 |
要執行的裝置目標。 |
id |
String |
必填。 裝置 ID (如 SYNC 提供的 ID)。 |
customData |
物件 |
如果在 SYNC 中提供了不透明的自訂資料物件,系統會在這裡傳送。 |
execution |
陣列 |
必填。 要在目標裝置上執行的指令清單。 |
[item, ...] |
物件 |
裝置指令。 |
command |
String |
必填。 要執行的指令,通常含有隨附的參數。 |
params |
物件 |
與每個指令的參數一致。 |
範例
執行意願要求
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123", "customData": { "fooValue": 74, "barValue": true, "bazValue": "sheepdip" } }, { "id": "456", "customData": { "fooValue": 36, "barValue": false, "bazValue": "moarsheep" } } ], "execution": [ { "command": "action.devices.commands.OnOff", "params": { "on": true } } ] } ] } } ] }
回應格式
欄位 | 類型 | 說明 |
---|---|---|
requestId |
String |
必填。 相應要求的 ID。 |
payload |
物件 |
必填。 意圖回應酬載。 |
errorCode |
String |
整個交易的錯誤代碼,以及驗證失敗的開發人員和開發人員系統錯誤。對於個別裝置錯誤,請使用裝置物件中的 errorCode。 |
debugString |
String |
永遠不會向使用者顯示這項錯誤,但可能會在開發期間記錄或使用。 |
commands |
陣列 |
每個物件都包含一或多部具有回應詳細資料的裝置。注意:這些內容與請求的分組方式可能不同。舉例來說,請求可能會開啟 7 盞燈,其中 3 盞燈成功,4 盞燈故障,因此回應中有兩個群組。 |
[item, ...] |
物件 |
裝置執行結果。 |
ids |
陣列 |
必填。 與這個狀態對應的裝置 ID 清單。 |
[item, ...] |
String |
裝置 ID。 |
status |
String |
必填。 執行作業的結果。 支援的值:
|
states |
物件 |
與每個特徵結構定義參考資料中描述的個別特性對齊。這些是執行後的狀態 (如果有的話)。 |
online |
布林 |
指出裝置是否連上網路 (即可存取)。 |
errorCode |
String |
視需要從預設錯誤代碼展開 ERROR 狀態,該值會對應至使用者看到的錯誤。 |
範例
執行意願回應
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "on": true, "online": true } }, { "ids": [ "456" ], "status": "ERROR", "errorCode": "deviceTurnedOff" } ] } }