action.devices.SYNC

這個意圖會要求取得與指定使用者和使用者功能相關聯的裝置清單。

會在帳戶連結或使用者期間觸發 手動重新同步裝置。您的執行要求應以 支援的特性和屬性

您的 SYNC 回應應會傳回所有與使用者相關聯的裝置。 但無法判斷能否連上任何特定裝置。這個程序是由 QUERYEXECUTE 則回應。

詳情請參閱「識別並同步處理」。

要求格式

欄位 類型 說明
requestId String

必要。

要求的 ID。

inputs 陣列

必要。

符合意圖要求的輸入清單。

[item, ...] 物件

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

intent

必要。

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

意圖要求類型。

範例

同步意圖要求

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}

回應格式

欄位 類型 說明
requestId String

必要。

對應要求的 ID。

payload 物件

必要。

意圖回應酬載。

agentUserId String

必要。

反映代理程式平台上的不重複 (且不可變更) 使用者 ID。對 Google 而言,這個字串不透明,因此如果代理程式端的表單無法變更,或是可變動的形式,請使用無法變更的格式 (例如是帳號,而非電子郵件)。

errorCode String

針對 SYNC 的系統錯誤

debugString String

詳細的錯誤不會向使用者顯示,但可能會在開發期間記錄或使用。

devices 陣列

必要。

使用者擁有的裝置清單。系統傳回零或更多裝置 (沒有任何裝置、使用者沒有任何裝置,或已中斷所有裝置的連線)。

[item, ...] 物件

裝置中繼資料。

id String

必要。

開發人員雲端中的裝置 ID。此 ID 對使用者和開發人員而言皆不得重複,因為在分享時,我們可能會用這個 ID 刪除同一部裝置的重複檢視畫面。裝置本身無法變更。如有任何變更,Google 助理就會將其視為新裝置。

type String

必要。

裝置的硬體類型。

traits 陣列

必要。

這部裝置的特徵清單。這會定義裝置支援的指令、屬性和狀態。

[item, ...] String

支援的特徵名稱。

name 物件

必要。

這部裝置的名稱。

defaultNames 陣列

開發人員 (而非使用者) 提供的名稱清單,通常包含製造商名稱、SKU 等

[item, ...] String

裝置預設名稱。

name String

必要。

裝置的主要名稱,通常由使用者提供。這也是 Google 助理在回應中會優先描述裝置的名稱。

nicknames 陣列

使用者提供的裝置其他名稱。

[item, ...] String

裝置暱稱。

willReportState 布林值

必要。

指出這部裝置是否會透過即時動態消息更新狀態。(設為 true 時使用即時動態饋給回報狀態,設為 false 則使用輪詢模型)。

notificationSupportedByAgent 布林值

(預設值:false)

用於指出裝置是否已啟用通知功能。

roomHint String

提供裝置目前在使用者家中的房間,簡化設定程序。

deviceInfo 物件

包含用於說明裝置,視需要在需要一次性邏輯下使用的裝置 (例如「韌體版本 X 的韌體版本 X 需要調整顏色」或是「安全性漏洞要求通知所有韌體 Z 使用者」)。

manufacturer String

當開發人員做為其他裝置的中心時,特別實用。舉例來說,Google 可能會在這裡提供製造商標準清單,例如:TP-Link 和 Smartthings 都可用來描述「osram」使用這個層即可

model String

特定裝置的型號或 SKU ID。

hwVersion String

硬體附加的特定版本號碼 (如有)。

swVersion String

軟體/韌體附加的特定版本號碼 (如有)。

attributes 物件

與每個特徵結構定義參考資料所述的個別特徵屬性對齊。

customData 物件

開發人員定義的物件,會附加至未來的 QUERY 和 EXECUTE 要求,每部裝置最多 512 個位元組。這個物件可用來儲存雲端服務可能需要裝置的其他資訊,例如裝置的全球區域。這個物件中的資料有一些限制:沒有機密資訊,包括但不限於個人識別資訊。

otherDeviceIds 陣列

用於辨識雲端同步裝置的替代 ID 清單,以便在本機執行。

[item, ...] 物件

替代裝置 ID。

agentId String

服務專員的 ID。通常是 Actions 主控台中的專案 ID。

deviceId String

必要。

由代理程式定義的裝置 ID,裝置 ID 不得重複。

範例

同步意圖回應

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.OUTLET",
        "traits": [
          "action.devices.traits.OnOff"
        ],
        "name": {
          "defaultNames": [
            "My Outlet 1234"
          ],
          "name": "Night light",
          "nicknames": [
            "wall plug"
          ]
        },
        "willReportState": false,
        "roomHint": "kitchen",
        "deviceInfo": {
          "manufacturer": "lights-out-inc",
          "model": "hs1234",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        },
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id"
          }
        ],
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      },
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting"
        ],
        "name": {
          "defaultNames": [
            "lights out inc. bulb A19 color hyperglow"
          ],
          "name": "lamp1",
          "nicknames": [
            "reading lamp"
          ]
        },
        "willReportState": false,
        "roomHint": "office",
        "attributes": {
          "colorModel": "rgb",
          "colorTemperatureRange": {
            "temperatureMinK": 2000,
            "temperatureMaxK": 9000
          },
          "commandOnlyColorSetting": false
        },
        "deviceInfo": {
          "manufacturer": "lights out inc.",
          "model": "hg11",
          "hwVersion": "1.2",
          "swVersion": "5.4"
        },
        "customData": {
          "fooValue": 12,
          "barValue": false,
          "bazValue": "bar"
        }
      }
    ]
  }
}