智慧型住宅安全系統指南
action.devices.types.SECURITYSYSTEM - 保全系統可啟動及解除。感應器可以在多個安全等級 (例如在家或外出) 中啟動，並回報特定感應器的相關資訊，例如可偵測動作或已開啟窗戶的感應器。
這個類型表示裝置會取得安全系統圖示和一些相關的同義詞和別名。
裝置功能
請參閱相應特徵說明文件，進一步瞭解實作詳細資料，例如您的服務應支援的屬性和聲明，以及如何建構 EXECUTE 和 QUERY 回應。
必要 traits
這些特徵和指令為必要項目 (如適用)。如果您的裝置不支援這些特性，請在 QUERY 或 EXECUTE 回應中輸入 functionNotSupported 的錯誤代碼。詳情請參閱「錯誤和例外狀況」一節。
建議的 traits
建議使用這些特徵 (如適用)。 不過，您也可以自由混用所有可用特質，以與現有產品功能最完美搭配。
品質規定
- 延遲時間：必須小於或等於 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"
}
]
}
}
}
}
執行指令範例
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"
}
]
}
}
]
}
}
採用雙重驗證做為架構
如果啟動流程要求使用者透過雙重驗證對話方塊輸入 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
}
}
]
}
}