action.devices.EXECUTE

這個意圖會傳送要在智慧住宅裝置上執行的指令。

執行要求應處理每個指令、將命令傳送到相應的裝置，然後傳回 EXECUTE 回應中的新狀態。

單一 EXECUTE 意圖可利用多個指令指定多部裝置。 舉例來說，觸發的意圖可能會在一組裝置上同時設定亮度和顏色 也可以將多個燈具設為不同的顏色。

詳情請參閱「查詢並執行」。

要求格式

欄位	類型	說明
requestId	String	必要。 要求的 ID。
inputs	陣列	必要。 符合意圖要求的輸入清單。
[item, ...]	物件	與意圖要求相關聯的類型和酬載。
intent		必要。 (常數值："action.devices.EXECUTE") 意圖要求類型。
payload	物件	必要。 EXECUTE 要求酬載。
commands	陣列	必要。 裝置目標和指令組合的清單。
[item, ...]	物件	要在連接的裝置目標上執行的指令組合。
devices	陣列	必要。 目標裝置清單。
[item, ...]	物件	要執行的裝置目標。
id	String	必要。 裝置 ID；與 SYNC 中提供的 ID 相同。
customData	物件	如果您在 SYNC 中提供不透明 customData 物件，該物件會傳送至這裡。
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	必要。 執行作業的結果。 支援的值： SUCCESS 確認指令執行成功。 PENDING 指令已排入佇列，但預期會成功。 OFFLINE 目標裝置處於離線狀態或無法存取。 EXCEPTIONS 有與指令相關的問題或快訊。指令可能會成功或失敗。通常當您想傳送其他已連結裝置的相關資訊時，就會設定這種狀態類型。 ERROR 目標裝置無法執行指令。
states	物件	與每個特徵結構定義參考資料中所述的個別特徵狀態對齊。這些是執行後的狀態 (如有)。
online	布林值	說明裝置是否連上網路 (也就是可連線)。
errorCode	String	視需要從預設的錯誤代碼展開「錯誤」狀態，這會對應至向使用者顯示的錯誤。

範例

執行意圖回應

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      },
      {
        "ids": [
          "456"
        ],
        "status": "ERROR",
        "errorCode": "deviceTurnedOff"
      }
    ]
  }
}