智慧型住宅安全系統指南
action.devices.types.SECURITYSYSTEM - 可啟動及解除保全系統。可以設定多種安全等級 (例如在家和外出)，並回報特定感應器的資訊，例如偵測動作或開窗的感應器。
這類型表示裝置會取得「安全系統」圖示，以及一些相關的近義字和別名。
裝置功能
請參閱對應特徵的說明文件，瞭解實作詳細資訊，例如服務應支援的屬性和狀態，以及如何建構 EXECUTE 和 QUERY 回應。
必要特徵
這些特徵和指令 (如果適用於您的裝置) 是必要的。如果裝置不支援這些特徵，請在 QUERY 或 EXECUTE 回應中輸入 functionNotSupported 的錯誤代碼。詳情請參閱「錯誤和例外狀況」一文。
建議特徵
如果這些特徵適用於您的裝置，建議您使用這些特徵。不過，您可以自由混搭所有可用的特徵，以便配合現有產品功能。
品質規定
- 延遲時間：必須小於或等於 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": "EXCEPTIONS",
"states": {
"online": true,
"isArmed": false,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": true,
"priority": 0,
"statusCode": "windowOpen",
"deviceTarget": "sensor_id1"
}
]
}
}
]
}
}使用雙重驗證功能啟動警報
如果啟動流程要求使用者透過雙因素驗證對話方塊輸入 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 碼。為了支援第二次回合，您應回覆 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 } } ] } }