スマートホーム セキュリティ システム ガイド
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": "PENDING", "states": { "online": true, "isArmed": true, "currentArmLevel": "away_key" } } ] } }
デバイスエラー
エラーと例外の全リストをご覧ください。アーム例外を報告する
システムを監視または監視を解除しようとするときに、StatusReport トレイトを通じて報告する例外コードで追加のコンテキストを提供できます。例外は、ブロックまたは非ブロックとして報告できます。
- ステータスが「SUCCESS」で報告されたブロックしない例外は、例外によって作動または解除が妨げられなかったことを示します。
- ステータスが「EXCEPTIONS」で報告されたブロック例外は、これらの例外が原因で、作動または解除が停止したことを示します。
セキュリティ システムに関連する一般的な例外コードは次のとおりです。
doorOpen: ドアが開いています。windowOpen: ウィンドウが開いています。isOpen: センサーが、何かが開いていることを検出しました（ただしそれがドアか窓かはわかりません）。
例: ブロックを引き起こさない例外
この例は、窓が開いていると報告されても、セキュリティ システムが作動するという非ブロック例外を示しています。
| ユーザー | セキュリティ システムを高セキュリティに設定して。 |
| Google アシスタント | OK、前部座席の窓が開いています。セキュリティ システムを高セキュリティに設定します。 |
{
"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 } } ] } }