スマートホーム セキュリティ システム ガイド
action.devices.types.SECURITYSYSTEM - セキュリティ システムでは、監視と監視の解除を行えます。さらに複数のセキュリティ レベル（自宅や外出先など）での監視や、特定のセンサー（動作や開いている窓を検知するセンサーなど）に関する情報の報告ができます。
このタイプのデバイスにはセキュリティ システムのアイコンが設定され、類義語や別名が与えられます。
デバイスの機能
サービスがサポートする必要がある属性や状態、EXECUTE レスポンスと QUERY レスポンスの作成方法などの実装の詳細については、対応するトレイトのドキュメントをご覧ください。
必須のトレイト
これらの特性とコマンドは、デバイスに該当する場合に必要です。デバイスがこれらのトレイトをサポートしていない場合は、QUERY または EXECUTE レスポンスで functionNotSupported のエラーコードを入力します。詳しくは、エラーと例外をご覧ください。
推奨されるトレイト
これらのトレイトは、デバイスに適用できる場合は推奨されます。ただし、利用可能なすべてのトレイトの中から、既存の製品機能に最適な組み合わせを自由に選択できます。
デバイスの例: シンプルなセキュリティ システム
このセクションでは、上記のデバイスタイプとトレイトに基づく一般的な「セキュリティ システム」を表すインテント ペイロードの例を示します。実装でトレイトを追加または削除した場合は、それらの変更を反映するようにレスポンスを適宜変更します。
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": "EXCEPTIONS",
"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 } } ] } }