スマートホーム セキュリティ システム ガイド
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
}
}
]
}
}