action.devices.QUERY

這項意圖會查詢目前裝置的狀態,包括裝置是否可連上網路。

QUERY 回應應只會傳回狀態資訊。更新裝置的屬性和特徵,由 SYNC 回應處理。

詳情請參閱「查詢」和「執行」

要求格式

欄位 類型 說明
requestId String

必填。

要求的 ID。

inputs 陣列

必填。

與意圖要求相符的輸入清單。

[item, ...] 物件

與意圖要求相關聯的類型和酬載。

intent

必填。

(常數值:"action.devices.QUERY")

意圖要求類型。

payload 物件

必填。

QUERY 要求酬載。

devices 陣列

必填。

目標裝置清單。

[item, ...] 物件

要查詢的裝置目標。

id String

必填。

裝置 ID (如 SYNC 提供的 ID)。

customData 物件

如果在 SYNC 中提供了不透明的自訂資料物件,系統會在這裡傳送。

範例

QUERY 意圖要求

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123",
            "customData": {
              "fooValue": 74,
              "barValue": true,
              "bazValue": "foo"
            }
          },
          {
            "id": "456",
            "customData": {
              "fooValue": 12,
              "barValue": false,
              "bazValue": "bar"
            }
          }
        ]
      }
    }
  ]
}

回應格式

欄位 類型 說明
requestId String

必填。

相應要求的 ID。

payload 物件

必填。

意圖回應酬載。

errorCode String

整個交易的錯誤代碼,以及驗證失敗的開發人員和開發人員系統錯誤。對於個別裝置錯誤,請使用裝置物件中的 errorCode。

debugString String

永遠不會向使用者顯示這項錯誤,但可能會在開發期間記錄或使用。

devices 物件

必填。

裝置地圖。將開發人員裝置 ID 對應至狀態屬性的物件。

<string> 物件

裝置狀態。

online 布林

必填。

指出裝置是否連上網路 (即可存取)。

status String

必填。

查詢作業的結果。

支援的值:

SUCCESS
確認查詢成功。
OFFLINE
目標裝置處於離線狀態或無法連上。
EXCEPTIONS
有與查詢相關的問題或快訊。查詢會成功或失敗。此狀態類型通常是當您想傳送其他已連結裝置的其他資訊時。
ERROR
無法查詢目標裝置。
errorCode String

視需要從預設錯誤代碼展開 ERROR 狀態,該值會對應至使用者看到的錯誤。

範例

QUERY 意圖回應

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true,
        "status": "SUCCESS"
      },
      "456": {
        "on": true,
        "online": true,
        "status": "SUCCESS",
        "brightness": 80,
        "color": {
          "spectrumRgb": 16711935
        }
      }
    }
  }
}