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`	物件	與每個指令的參數保持一致。

範例

EXECUTE 意圖要求

{
  "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	視需要從預設錯誤代碼擴充 ERROR 狀態，這會對應至向使用者顯示的錯誤。
`debugString`	String	詳細的命令層級錯誤，不會向使用者顯示，但可能會在開發期間記錄或使用。

範例

EXECUTE 意圖回應

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