action.devices.SYNC
此 intent 会请求与指定用户及其功能相关联的设备列表。
在帐号关联期间或用户手动重新同步其设备时触发。你的执行方式应响应每台设备支持的特征和属性。
您的 SYNC
响应应返回与用户关联的所有设备。这无法确定是否可连接到任何特定设备。这由 QUERY
和 EXECUTE
响应处理。
有关详情,请参阅识别和同步。
请求格式
字段 | 类型 | 说明 |
---|---|---|
requestId |
String |
必填。 请求的 ID。 |
inputs |
数组 |
必填。 与 intent 请求匹配的输入列表。 |
[item, ...] |
对象 |
与 intent 请求相关联的类型和载荷。 |
intent |
必填。 (常量值: intent 请求类型。 |
示例
SYNC intent 请求
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [ { "intent": "action.devices.SYNC" } ] }
响应格式
字段 | 类型 | 说明 |
---|---|---|
requestId |
String |
必填。 相应请求的 ID。 |
payload |
对象 |
必填。 intent 响应载荷。 |
agentUserId |
String |
必填。 反映代理平台上的唯一(且不可变)用户 ID。该字符串对 Google 来说是不透明的,因此,如果代理端存在不可变形式与可变形式,请使用不可变形式(例如,使用帐号而非电子邮件地址)。 |
errorCode |
String |
关于同步的系统错误 |
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 |
Boolean |
必填。 指明此设备的状态是否由实时 Feed 更新。(如需使用实时 Feed 报告状态,请选择 True;如果要使用轮询模型,则为 False)。 |
notificationSupportedByAgent |
Boolean |
(默认值: 指明设备是否已启用通知。 |
roomHint |
String |
提供用户住宅中设备的当前房间以简化设置。 |
deviceInfo |
对象 |
包含用于描述设备的字段,供一次性逻辑使用(例如,“已损坏的固件 X 号 Y 需要调整颜色”或“安全缺陷需要通知所有用户 Z 固件”)。 |
manufacturer |
String |
在开发者是其他设备的中心时,此功能特别有用。Google 可能会在此处提供标准的制造商列表,例如 TP-Link 和 Smartthings 对“osram”的描述方式相同。 |
model |
String |
特定设备的型号或 SKU 标识符。 |
hwVersion |
String |
附加到硬件的具体版本号(如果有)。 |
swVersion |
String |
软件/固件随附的具体版本号(如有)。 |
attributes |
对象 |
与每个特征架构参考中描述的每个特征属性一致。 |
customData |
对象 |
由开发者定义的将附加到以后的 QUERY 和 EXECUTE 请求的对象,每台设备最多 512 个字节。使用此对象可存储您的云服务可能需要的设备的其他信息,例如设备的全局区域。此对象中的数据存在一些限制:没有敏感信息,包括但不限于个人身份信息。 |
otherDeviceIds |
数组 |
用于标识要在本地执行的云同步设备的备用 ID 列表。 |
[item, ...] |
对象 |
备用设备 ID。 |
agentId |
String |
代理的 ID。通常,这是 Actions 控制台中的项目 ID。 |
deviceId |
String |
必填。 代理定义的设备 ID。设备 ID 必须是唯一的。 |
示例
SYNC intent 响应
{ "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" } } ] } }