智慧住宅安全系統指南
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」狀態回報的非封鎖例外狀況，表示例外狀況並未阻止設防或解除設防。
- 狀態為「例外狀況」的封鎖例外狀況表示由於這些例外狀況，系統停止了設防或解除設防作業。
與安全系統相關的常見例外狀況代碼包括：
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 挑戰，並提供額外資訊，包括目標 ARM 層級，以及含有封鎖例外狀況的目前狀態報告。
{ "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 } } ] } }