スマートホーム セキュリティ システム ガイド
action.devices.types.SECURITYSYSTEM
- セキュリティ システムでの監視を作動させることができます。複数のセキュリティ レベル(在宅と外出など)で監視を行うことができ、特定のセンサー(動作や開いているウィンドウを検出するセンサーなど)に関する情報を報告できます。
このタイプは、デバイスにセキュリティ システム アイコン、関連する類義語、エイリアスがあることを示します。
デバイスの機能
サービスがサポートする属性や状態、EXECUTE レスポンスと QUERY レスポンスの構築方法など、実装の詳細については、対応するトレイトのドキュメントをご覧ください。
必要な特性
これらのトレイトとコマンドは、お使いのデバイスに必須です。
推奨されるトレイト
これらのトレイトは、お客様のデバイスに該当する場合におすすめです。 ただし、既存のプロダクトの機能に合わせて、使用可能なすべてのトレイトを自由に組み合わせて使用できます。
品質要件
- レイテンシ: 2,000 ミリ秒以下にする必要があります。
- 信頼性: 97% 以上を指定します。
デバイスの例: シンプルなセキュリティ システム
このセクションでは、上記のデバイスタイプとトレイトに基づく、一般的な「セキュリティ システム」を表すインテント ペイロードの例について説明します。実装でトレイトを追加または削除する場合は、その変更を反映するようにレスポンスを変更します。
SYNC レスポンスの例
{ "requestId": "6894439706274654512", "inputs": [ { "intent": "action.devices.SYNC" } ] }
{ "requestId": "6894439706274654512", "payload": { "agentUserId": "user123", "devices": [ { "id": "123", "type": "action.devices.types.SECURITYSYSTEM", "traits": [ "action.devices.traits.StatusReport", "action.devices.traits.ArmDisarm" ], "name": { "name": "Simple security system" }, "willReportState": true, "attributes": { "availableArmLevels": { "levels": [ { "level_name": "home_key", "level_values": [ { "level_synonym": [ "Home and Guarding", "level 1", "home", "SL1" ], "lang": "en" } ] }, { "level_name": "away_key", "level_values": [ { "level_synonym": [ "Away and Guarding", "level 2", "away", "SL2" ], "lang": "en" } ] } ], "ordered": true } }, "deviceInfo": { "manufacturer": "smart-home-inc", "model": "hs1234", "hwVersion": "3.2", "swVersion": "11.4" } } ] } }
QUERY レスポンスの例
{ "requestId": "6894439706274654514", "inputs": [ { "intent": "action.devices.QUERY", "payload": { "devices": [ { "id": "123" } ] } } ] }
{ "requestId": "6894439706274654514", "payload": { "devices": { "123": { "status": "SUCCESS", "online": true, "isArmed": true, "currentArmLevel": "home_key", "currentStatusReport": [ { "blocking": false, "deviceTarget": "123", "priority": 0, "statusCode": "lowBattery" } ] } } } }
EXECUTE コマンドの例
ArmDisarm
コマンド パラメータの詳細については、
action.devices.traits.ArmDisarm
リファレンスをご覧ください。
{ "requestId": "6894439706274654516", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123" } ], "execution": [ { "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away_key" } } ] } ] } } ] }
{ "requestId": "6894439706274654516", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": true, "currentArmLevel": "away_key" } } ] } }
デバイスエラー
エラーと例外の全一覧をご覧ください。監視の例外を報告する
システムの監視や監視の解除を行う場合は、StatusReport トレイトで報告した例外コードに沿って追加コンテキストを提供できます。例外は「ブロック中」または「ブロックなし」として報告されることがあります。
- 「SUCCESS」ステータスで報告された「非ブロッキングの例外」は、その例外が監視の監視または解除を妨げなかったことを示します。
- 「EXCEPTIONS」ステータスで報告されたブロックの例外は、これらの例外が原因で監視が停止になったことを示しています。
一般にセキュリティ システムに関連する例外コードは次のとおりです。
doorOpen
: ドアが開いています。windowOpen
: ウィンドウが開いています。isOpen
: センサーは何かが開いていることを検出します(ただし、ドアや窓かどうかわかりません)。
例: 非ブロッキング例外
この例では、ウィンドウが開いていると報告されていても、セキュリティ システムが監視されている非ブロッキング例外を示しています。
ユーザー | セキュリティ システムを高セキュリティに設定する。 |
Google アシスタント | フロントウィンドウが開いています。セキュリティ システムを高セキュリティに設定します。 |
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "L2" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": false, "priority": 0, "statusCode": "windowOpen", "deviceTarget": "sensor_id1" } ] } } ] } }
例: 例外のブロック
ユーザー | セキュリティ システムを高セキュリティに設定する。 |
Google アシスタント | セキュリティ システムの操作中にエラーが発生しました。正面の窓が開いています。 |
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "L2" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": false, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": true, "priority": 0, "statusCode": "windowOpen", "deviceTarget": "sensor_id1" } ] } } ] } }
2 要素認証を使用する監視
監視フローで 2 要素認証ダイアログにユーザーが PIN を入力する必要がある場合は、有効な例外があるとき(ウィンドウまたはドアが開いているときなど)にシステムの監視を継続するかどうかを確認する必要があります。
このシナリオでは、PIN またはパスフレーズ エントリの両方の後に確認応答が必要になる場合があります。
例: 確認応答チャレンジ
この例では、ユーザーがセキュリティ システムでの監視を試みていますが、玄関が開いていると検出されています。ユーザーは、正面玄関が開いている場合でもセキュリティ システムでの監視を作動させる必要があることを認めます。
ユーザー | セキュリティ システムを作動させます。 |
Google アシスタント | 玄関は開いています。セキュリティ システムを作動してもよろしいですか? |
ユーザー | はい、 |
Google アシスタント | セキュリティシステムによる監視を開始します。 |
最初のターンでは、ackNeeded
チャレンジで応答する必要があります。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "ERROR", "errorCode": "challengeNeeded", "challengeNeeded": { "type": "ackNeeded" }, "states": { "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": false, "priority": 0, "statusCode": "doorOpen", "deviceTarget": "456" } ] } } ] } }
Google からのすべてのリクエストには ack
の結果が含まれます。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true }, "challenge": { "ack": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "isArmed": true } } ] } }
例: PIN の確認応答、本人確認
この例では、PIN 入力を必要とするセキュリティ システムでの監視をユーザーが行おうとしています。 システムは、前面と背面のウィンドウが開いていることを検出し、監視を進める必要があることの確認をユーザーに依頼します。
ユーザー | 監視モード。 |
Google アシスタント | PIN を入力してください。 |
ユーザー | 1234 です。 |
Google アシスタント | フロント ウィンドウとバック ウィンドウが開いているようです。セキュリティ システムによる監視を継続して完了してもよろしいですか? |
ユーザー | はい、 |
Google アシスタント | セキュリティシステムによる監視を開始します |
最初のターンは、標準の pinNeeded
チャレンジで応答します。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["456"], "status": "ERROR", "errorCode": "challengeNeeded", "challengeNeeded": { "type": "pinNeeded" } }] } }
Google は、提供された PIN を含むリクエストをフォローアップします。2 番目のターンをサポートするには、ターゲットのアームレベル、ブロック例外を含む現在のステータス レポートなど、追加情報を含む ackNeeded
チャレンジで応答する必要があります。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [...], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away" }, "challenge": { "pin": "1234" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["456"], "status": "ERROR", "states": { "targetArmLevel": "away", "currentStatusReport": [{ "blocking": true, "priority": 1, "deviceTarget": "front_window_id", "statusCode": "deviceOpen" }, { "blocking": true, "priority": 1, "deviceTarget": "back_window_id", "statusCode": "deviceOpen" } ] }, "errorCode": "challengeNeeded", "challengeNeeded": { "type": "ackNeeded" } }] } }
Google からのすべてのリクエストには、ack
の結果のみが含まれ、最初のターンに提供された PIN は含まれません。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [...], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away" }, "challenge": { "ack": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "isArmed": true } } ] } }