스마트 홈 보안 시스템 가이드

action.devices.types.SECURITYSYSTEM - 보안 시스템을 설정 및 해제할 수 있습니다. 여러 보안 수준 (예: 재택 및 외출)으로 설정할 수 있으며 움직임이나 열린 창을 감지하는 센서와 같은 특정 센서에 관한 정보를 보고할 수 있습니다.

이 유형은 기기가 보안 시스템 아이콘과 일부 관련 동의어 및 별칭을 가져옴을 나타냅니다.

기기 기능

서비스에서 지원해야 하는 속성 및 상태, EXECUTE 및 QUERY 응답을 빌드하는 방법 등 구현 세부정보는 해당 특성 문서를 참고하세요.

필수 특성

이러한 특성과 명령어는 기기에 적용되는 경우 필요합니다. 기기에서 이러한 특성을 지원하지 않으면 쿼리 또는 실행 응답에 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"
          }
        ]
      }
    }
  }
}

샘플 실행 명령어

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 특성을 통해 보고하는 예외 코드를 통해 추가 컨텍스트를 제공할 수 있습니다. 예외는 차단 또는 비차단으로 보고할 수 있습니다.

  • '성공' 상태로 보고된 차단되지 않는 예외는 예외로 인해 무장 또는 무장 해제가 방지되지 않았음을 나타냅니다.
  • '예외' 상태로 보고된 차단 예외는 이러한 예외로 인해 무장 또는 무장이 중지되었음을 나타냅니다.

일반적으로 보안 시스템과 관련된 예외 코드에는 다음이 포함됩니다.

  • 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"
            }
          }]
        }]
      }
    }]
  }
응답 2
{
    "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 또는 암호 입력과 확인이 모두 필요할 수 있습니다.

예: 확인 챌린지

이 예시에서는 사용자가 보안 시스템을 설정하려고 하지만 현관문이 열린 것으로 감지됩니다. 사용자는 현관문이 열려 있어도 보안 시스템이 설정되어야 함을 확인합니다.

사용자 보안 시스템을 설정합니다.
Google 어시스턴트 현관문이 열려 있습니다. 보안 시스템을 설정하시겠어요?
사용자 예.
Google 어시스턴트 알겠습니다. 보안 시스템을 설정합니다.

첫 번째 턴에서는 ackNeeded 챌린지로 응답해야 합니다.

요청 1
{
    "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
            }
          }]
        }]
      }
    }]
  }
응답 2
{
    "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 결과가 포함됩니다.

요청 2
{
    "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 챌린지로 응답해야 합니다.

요청 1
{
  "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 챌린지로 응답해야 합니다.

요청 2
{
  "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은 포함되지 않습니다.

요청 3
{
  "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
        }
      }
    ]
  }
}