スマートホーム セキュリティ システム ガイド
action.devices.types.SECURITYSYSTEM - セキュリティ システムでの監視や監視の解除を行えます。複数のセキュリティ レベル（在宅と外出など）での監視を可能にし、特定のセンサーに関する情報（動きや開いているウィンドウを検出するセンサーなど）を報告できます。
このタイプは、デバイスにセキュリティ システム アイコンと、関連する類義語やエイリアスがあることを示します。
デバイスの機能
サービスがサポートする属性や状態、EXECUTE レスポンスや QUERY レスポンスの作成方法など、実装の詳細については、対応するトレイトのドキュメントをご覧ください。
必要なトレイト
これらのトレイトとコマンドは、デバイスに応じて必要です。
推奨されるトレイト
これらのトレイトは、お使いのデバイスに推奨されます（推奨）。ただし、既存のプロダクトの機能に合わせて、利用可能なすべてのトレイトを自由に組み合わせてマッチングできます。
品質要件
- レイテンシ: 2000 ミリ秒 以下でなければなりません。
- 信頼性: 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
}
}
]
}
}