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。這對使用者和開發人員而言不能重複,因為共用時可能會重覆同一裝置的多次檢視畫面。裝置無法變更。當裝置變更時,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 的韌體版本 Y 需要調整顏色」或「安全性瑕疵需要通知所有使用者 韌體 Z」)。

manufacturer String

當開發人員是其他裝置的中樞時,特別實用。Google 可在此提供標準製造商名單,例如 TP-Link 和 Smartthings 都會以「方式」描述。

model String

特定裝置的型號或 SKU ID。

hwVersion String

硬體已安裝的特定版本號碼 (如果有的話)。

swVersion String

連接至軟體/韌體的特定版本號碼 (如果有的話)。

attributes 物件

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

customData 物件

開發人員定義的物件,系統會將其附加至日後的 QUERY 和 EXECUTE 要求中,每個裝置最多 512 個位元組。請使用這個物件來儲存雲端服務所需的裝置額外資訊,例如裝置的全球區域。這個物件中的資料有以下限制:沒有任何機密資訊,包括但不限於個人識別資訊。

otherDeviceIds 陣列

替代 ID 清單,用於識別執行本機執行作業的雲端同步裝置。

[item, ...] 物件

替代裝置 ID。

agentId String

服務專員的 ID。一般來說,這是動作控制台中的專案 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"
        }
      }
    ]
  }
}