action.devices.SYNC
このインテントは、指定されたユーザーとその機能に関連付けられているデバイスのリストをリクエストします。
アカウントのリンク時、またはユーザーが手動でデバイスを再同期したときにトリガーされます。フルフィルメントは、各デバイスでサポートされているトレイトと属性を返す必要があります。
SYNC
レスポンスは、ユーザーに関連付けられているすべてのデバイスを返します。どのデバイスにも到達可能かどうかわかりません。これは QUERY
レスポンスと EXECUTE
レスポンスによって処理されます。
詳しくは、特定と同期をご覧ください。
リクエストの形式
フィールド | タイプ | 説明 |
---|---|---|
requestId |
文字列 |
必須。 リクエストの ID。 |
inputs |
配列 |
必須。 インテント リクエストと一致する入力のリスト。 |
[item, ...] |
オブジェクト |
インテント リクエストに関連付けられているタイプとペイロード。 |
intent |
必須。 (定数値: インテント リクエストのタイプ。 |
例
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 |
ブール値 |
(デフォルト: デバイスで通知が有効になっているかどうかを示します。 |
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" } } ] } }