遷移至 Google Home 開發人員中心已完成。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

action.devices.SYNC

這項意圖會要求與指定使用者相關聯的裝置清單及其功能。

系統會在帳戶連結期間或使用者手動重新同步裝置時觸發這項事件。你的履行服務應針對每部裝置，回應支援的特徵和屬性。

SYNC 回應應傳回與使用者相關聯的所有裝置。這不會判斷任何特定裝置是否可連線，而是由 QUERY 和 EXECUTE 回應處理。

要求格式

欄位	類型	說明
`requestId`	String	必要。要求 ID。
`inputs`	陣列	必要。符合意圖要求的輸入內容清單。
`[item, ...]`	物件	與意圖要求相關聯的類型和酬載。
`intent`		必要。 (常數值：`"action.devices.SYNC"`) 意圖要求類型。

範例

SYNC 意圖要求

{
  "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 來排除重複的瀏覽次數。裝置的 ID 應為不可變更，如果變更，Google 助理會將其視為新裝置。
`type`	String	必要。裝置的硬體類型。必須符合以下模式：`^action.devices.types.[a-zA-z]+$`。
`traits`	陣列	必要。這部裝置的特徵清單。這會定義裝置支援的指令、屬性和狀態。
`[item, ...]`	String	支援的特徵名稱。必須符合以下模式：`^action.devices.traits.[a-zA-z]+$`。
`name`	物件	必要。這部裝置的名稱。
`defaultNames`	陣列	開發人員提供的名稱清單，而非使用者提供的名稱，通常是製造商名稱、SKU 等。
`[item, ...]`	String	裝置預設名稱。
`name`	String	必要。裝置的主要名稱，通常由使用者提供。這也是 Google 助理在回覆中描述裝置時偏好的名稱。如果名稱超過 60 個 Unicode 碼點 (字元) 的限制，系統會截斷名稱，但不會擲回錯誤。開發人員有責任處理長名稱。
`nicknames`	陣列	使用者為裝置提供的其他名稱。
`[item, ...]`	String	裝置暱稱。
`willReportState`	布林值	必要。指出這個裝置的狀態是否會透過即時動態消息更新。(設為 true 可使用即時動態饋給回報狀態，設為 false 則使用輪詢模型)。
`notificationSupportedByAgent`	布林值	(預設值：`false`) 指出裝置是否已啟用通知。
`roomHint`	String	提供使用者住家中裝置的目前房間，簡化設定程序。
`deviceInfo`	物件	包含描述裝置的欄位，可在需要時用於一次性邏輯 (例如「燈具 Y 的韌體版本 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 不得重複。

範例

SYNC 意圖回應

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