스마트 홈 보안 시스템 가이드
action.devices.types.SECURITYSYSTEM
- 보안 시스템을 설정하거나 해제할 수 있습니다. 여러 보안 수준 (예: 재택 및 외출)으로 무장하고 움직임을 감지하는 센서나 열린 창문과 같은 특정 센서에 관한 정보를 보고할 수 있습니다.
이 유형은 기기에 보안 시스템 아이콘과 일부 관련 동의어 및 별칭이 표시된다는 것을 나타냅니다.
기기 기능
서비스에서 지원해야 하는 속성 및 상태, EXECUTE 및 QUERY 응답을 빌드하는 방법과 같은 구현 세부정보는 상응하는 트레잇 문서를 참고하세요.
필수 trait
기기에 해당되는 경우 이러한 특성과 명령어는 필수입니다. 기기에서 이러한 트레잇을 지원하지 않으면 쿼리 또는 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" } } ] } }
샘플 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" } } ] } }
기기 ERRORS
오류 및 예외의 전체 목록을 참조하세요.경보 시스템 예외 보고
시스템을 경보 시스템을 설정하거나 해제하려고 할 때 StatusReport 트레잇을 통해 보고하는 예외 코드를 통해 추가 컨텍스트를 제공할 수 있습니다. 예외는 차단 또는 비차단으로 보고될 수 있습니다.
- 'SUCCESS' 상태로 보고된 비차단 예외는 예외로 경보 시스템 설정 또는 해제가 방지되지 않았음을 나타냅니다.
- 'EXCEPTIONS' 상태로 보고된 차단 예외는 이러한 예외로 인해 경보 시스템 설정 또는 해제가 중지되었음을 나타냅니다.
보안 시스템과 일반적으로 관련된 예외 코드는 다음과 같습니다.
doorOpen
: 문이 열려 있습니다.windowOpen
: 창이 열려 있습니다.isOpen
: 센서가 무언가가 열려 있음을 감지하지만 문인지 창인지는 모릅니다.
예: 비차단 예외
이 예는 창이 열린 것으로 보고되지만 보안 시스템이 설정된 경우의 비차단 예외를 보여줍니다.
사용자(User) | 보안 시스템을 높은 보안으로 설정합니다. |
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"
}
]
}
}
]
}
}
예: 차단 예외
사용자(User) | 보안 시스템을 높은 보안으로 설정합니다. |
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"
}
]
}
}
]
}
}
2단계 인증으로 경보 시스템 설정
보안 흐름에서 사용자에게 2단계 인증 대화상자를 통해 PIN을 입력해야 하는 경우 활성 예외가 있을 때 (예: 창 또는 문이 열려 있을 때) 사용자가 경보 시스템을 계속 설정할지 확인해야 합니다.
이 시나리오에서는 PIN 또는 암호 입력 모두에 이어 확인이 필요할 수 있습니다.
예: 확인 챌린지
이 예에서는 사용자가 보안 경보 시스템을 설정하려고 하지만 현관문이 열려 있는 것으로 감지된 경우를 보여줍니다. 사용자는 현관문이 열려 있더라도 보안 시스템이 설정되어 있어야 함을 인정합니다.
사용자(User) | 보안 시스템을 설정합니다. |
Google 어시스턴트 | 현관문이 열려 있습니다. 보안 경보 시스템을 설정하시겠습니까? |
사용자(User) | 저도요 |
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 입력을 요구하는 보안 시스템을 설정하려고 시도하는 사용자를 보여줍니다. 시스템이 전면 및 후면 창이 열려 있음을 감지하고 경보 시스템이 계속 진행되어야 하는지 확인하도록 사용자에게 요청합니다.
사용자(User) | 외출 경보 시스템 설정 |
Google 어시스턴트 | PIN을 입력하세요. |
사용자(User) | 1234입니다. |
Google 어시스턴트 | 전면 창문과 후면 창이 열려 있는 것 같습니다. 보안 경보 시스템을 외출 모드로 계속 설정하시겠어요? |
사용자(User) | 저도요 |
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 } } ] } }