action.devices.SYNC

このインテントは、指定されたユーザーとその機能に関連付けられているデバイスのリストをリクエストします。

アカウントのリンク時、またはユーザーが手動でデバイスを再同期したときにトリガーされます。フルフィルメントは、各デバイスでサポートされているトレイトと属性を返す必要があります。

SYNC レスポンスは、ユーザーに関連付けられているすべてのデバイスを返します。どのデバイスにも到達可能かどうかわかりません。これは QUERY レスポンスと EXECUTE レスポンスによって処理されます。

詳しくは、特定と同期をご覧ください。

リクエストの形式

フィールド タイプ 説明
requestId 文字列

必須。

リクエストの ID。

inputs 配列

必須。

インテント リクエストと一致する入力のリスト。

[item, ...] オブジェクト

インテント リクエストに関連付けられているタイプとペイロード。

intent

必須。

(定数値: "action.devices.SYNC"

インテント リクエストのタイプ。

SYNC インテント リクエスト

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}

レスポンスの形式

フィールド タイプ 説明
requestId 文字列

必須。

対応するリクエストの ID。

payload オブジェクト

必須。

インテント レスポンスのペイロード。

agentUserId 文字列

必須。

エージェントのプラットフォームで一意の(不変の)ユーザー ID を表します。この文字列は Google からは見えないため、エージェント側に不変な形式と可変な形式がある場合は、不変な形式を使用します(例: メールアドレスではなくアカウント番号)。

errorCode 文字列

SYNC での体系的なエラー

debugString 文字列

エラーの詳細。ユーザーには表示されませんが、開発中にログに記録または使用される可能性があります。

devices 配列

必須。

ユーザーが所有するデバイスのリスト。0 台以上のデバイスが返されます(ユーザーが 0 台のデバイスがある場合、つまり、ユーザーがデバイスがないか、すべてのデバイスを切断)。

[item, ...] オブジェクト

デバイスのメタデータ。

id 文字列

必須。

デベロッパーのクラウド内のデバイスの ID。これは、ユーザーとデベロッパーにとって一意でなければなりません。共有の際、同じデバイスの複数のビューを重複排除するために使用されることがあるためです。デバイスで不変である必要があります。変更されると、アシスタントはそのデバイスを新しいデバイスとして扱います。

type 文字列

必須。

デバイスのハードウェアの種類。

traits 配列

必須。

このデバイスに含まれるトレイトのリスト。デバイスがサポートするコマンド、属性、状態を定義します。

[item, ...] 文字列

サポートされているトレイトの名前。

name オブジェクト

必須。

デバイスの名前。

defaultNames 配列

ユーザーではなくデベロッパーが指定した名前(多くの場合はメーカー名や SKU など)のリスト

[item, ...] 文字列

デバイスのデフォルトの名前。

name 文字列

必須。

デバイスのプライマリ名。通常はユーザーが提供します。アシスタントがレスポンスの中でデバイスを示す名前でもあります。

nicknames 配列

ユーザーがデバイスに付けた追加の名前。

[item, ...] 文字列

デバイスのニックネーム。

willReportState ブール値

必須。

このデバイスの状態がリアルタイム フィードによって更新されるかどうかを示します(リアルタイムのフィードを状態の報告に使用する場合は true、ポーリング モデルを使用する場合は false にします)。

notificationSupportedByAgent ブール値

(デフォルト: false

デバイスで通知が有効になっているかどうかを示します。

roomHint 文字列

セットアップを簡素化するために、ユーザー宅内で現在デバイスがある部屋を示します。

deviceInfo オブジェクト

必要に応じてデバイスを 1 回限りのロジックで使用するためのフィールドが含まれています(例: 「ファームウェア バージョン X のライト Y が破損している場合、色を調整する必要があります」、「セキュリティの欠陥によりすべてのユーザーにファームウェア Z に通知する必要があります」)。

manufacturer 文字列

デベロッパーが他のデバイスのハブであるときは特に有用です。たとえば、TP-Link と Smartthings の両方が「osram」を同じように表すよう、Google がここでメーカーの標準リストを提供する場合があります。

model 文字列

特定デバイスのモデルまたは SKU ID。

hwVersion 文字列

ハードウェアのバージョン番号(ある場合)。

swVersion 文字列

ソフトウェア / ファームウェアのバージョン番号(ある場合)。

attributes オブジェクト

各トレイトのスキーマ リファレンスに記載されているトレイトごとの属性に沿います。

customData オブジェクト

デベロッパーが定義する QUERY および EXECUTE リクエストにアタッチされるオブジェクト(デバイスあたり最大 512 バイト)。このオブジェクトを使用して、クラウド サービスに必要なデバイスに関する追加情報(デバイスのグローバル リージョンなど)を保存します。このオブジェクトのデータにはいくつかの制約があります。機密情報(個人を特定できる情報など)は含まれません。

otherDeviceIds 配列

ローカルで実行するクラウド同期デバイスを識別するために使用される代替 ID のリストです。

[item, ...] オブジェクト

代替デバイス ID。

agentId 文字列

エージェントの ID。通常は、Actions Console のプロジェクト ID です。

deviceId 文字列

必須。

エージェントによって定義されたデバイス 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"
        }
      }
    ]
  }
}