action.devices.SYNC
這項意圖會要求與指定使用者及其裝置相關的裝置清單。
系統會在帳戶連結或使用者手動重新同步處理裝置時觸發這則訊息。您的出貨要求應針對每個裝置支援的屬性和屬性回應。
SYNC
回應應傳回與使用者相關聯的所有裝置。無法確定特定裝置是否能連線。這項作業由 QUERY
和 EXECUTE
回應來處理。
詳情請參閱「識別與同步」。
要求格式
欄位 | 類型 | 說明 |
---|---|---|
requestId |
String |
必填。 要求的 ID。 |
inputs |
陣列 |
必填。 與意圖要求相符的輸入清單。 |
[item, ...] |
物件 |
與意圖要求相關聯的類型和酬載。 |
intent |
必填。 (常數值: 意圖要求類型。 |
範例
同步意圖要求
{ "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 |
布林 |
(預設: 指出裝置是否已啟用通知功能。 |
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" } } ] } }