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 中提供了不透明的自訂資料物件，系統會在這裡傳送。
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	視需要從預設錯誤代碼展開 ERROR 狀態，該值會對應至使用者看到的錯誤。

範例

執行意願回應

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