action.devices.SYNC

此 intent 用于请求与指定用户关联的设备及其功能的列表。

它会在账号关联期间或在用户手动重新同步其设备时触发。您的执行方式应针对每台设备返回受支持的特征和属性。

您的 SYNC 响应应返回与用户关联的所有设备。 这并不决定任何特定设备是否可访问。这由 QUERYEXECUTE 响应处理。

如需了解详情,请参阅识别和同步

请求格式

字段 类型 说明
requestId String

必填。

请求的 ID。

inputs 数组

必填。

与意图请求匹配的输入列表。

[item, ...] 对象

与 intent 请求关联的类型和载荷。

intent

必填。

(常量值:"action.devices.SYNC"

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 布尔值

(默认值:false

指示设备是否已启用通知。

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"
        }
      }
    ]
  }
}