스마트 홈 보안 시스템 가이드
action.devices.types.SECURITYSYSTEM
- 보안 시스템을 설정하거나 해제할 수 있습니다. 또한 다양한 보안 수준 (예: 재택 및 외출)으로 경보 시스템을 설정할 수 있으며 움직임을 감지하는 센서나 열린 창문과 같은 특정 센서에 관한 정보를 보고할 수 있습니다.
이 유형은 기기에 보안 시스템 아이콘과 일부 관련 동의어 및 별칭을 가져옴을 나타냅니다.
기기 기능
서비스에서 지원해야 하는 속성 및 상태, EXECUTE 및 QUERY 응답을 빌드하는 방법 등 구현 세부정보는 해당하는 특성 문서를 참고하세요.
필수 trait
기기에 해당되는 경우 이러한 특성과 명령어가 필요합니다. 기기가 이러한 특성을 지원하지 않으면 QUERY 또는 EXECUTE 응답에 functionNotSupported
의 오류 코드를 입력하세요. 자세한 내용은 오류 및 예외를 참고하세요.
추천 특성
기기에 해당되는 경우 이러한 특성이 권장됩니다. 하지만 기존 제품 기능에 가장 잘 일치하도록 사용 가능한 모든 특성을 자유롭게 조합할 수 있습니다.
품질 요구사항
- 지연 시간: 2000ms 이하여야 합니다.
- 안정성: 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" } } ] } }
샘플 쿼리 응답
{ "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이 포함된 요청을 보냅니다. 두 번째 차례를 지원하려면 타겟 실험 부문 수준을 포함한 추가 정보와 차단 예외가 있는 현재 상태 보고서와 함께 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 } } ] } }