action.devices.SYNC
此 intent 用于请求与指定用户关联的设备及其功能的列表。
它会在账号关联期间或在用户手动重新同步其设备时触发。您的执行方式应针对每台设备返回受支持的特征和属性。
您的 SYNC
响应应返回与用户关联的所有设备。
这并不决定任何特定设备是否可访问。这由 QUERY
和 EXECUTE
响应处理。
如需了解详情,请参阅识别和同步。
请求格式
字段 | 类型 | 说明 |
---|---|---|
requestId |
String |
必填。 请求的 ID。 |
inputs |
数组 |
必填。 与意图请求匹配的输入列表。 |
[item, ...] |
对象 |
与 intent 请求关联的类型和载荷。 |
intent |
必填。 (常量值: intent 请求类型。 |
示例
SYNC 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 |
数组 |
必填。 相应设备具有的 trait 的列表。此文件定义了设备支持的命令、属性和状态。 |
[item, ...] |
String |
支持的特征的名称。 |
name |
对象 |
必填。 此设备的名称。 |
defaultNames |
数组 |
由开发者而非用户提供的名称列表,通常是制造商名称、SKU 等。 |
[item, ...] |
String |
设备默认名称。 |
name |
String |
必填。 设备的主名称,通常由用户提供。这也是 Google 助理在回答中描述设备时首选的名称。如果名称超过 60 个 Unicode 码位(字符)的限制,系统会截断名称,但不会抛出任何错误。开发者负责处理过长的名称。 |
nicknames |
数组 |
用户为设备提供的其他名称。 |
[item, ...] |
String |
设备别名。 |
willReportState |
布尔值 |
必填。 指示相应设备的状态是否会通过实时 Feed 进行更新。(true 表示使用实时 Feed 报告状态,false 表示使用轮询模型。) |
notificationSupportedByAgent |
布尔值 |
(默认值: 指示设备是否已启用通知。 |
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" } } ] } }