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。此 ID 對使用者和開發人員而言皆不得重複,因為在分享時,我們可能會用這個 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 的韌體版本 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" } } ] } }