스마트 홈 작업을 개발하는 방법을 알아볼 수 있는 새로운 공간인 Google Home 개발자 센터에 오신 것을 환영합니다. 참고: Actions 콘솔에서 작업을 계속 만들 수 있습니다.
컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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

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

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

기기 기능

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

필수 특성

기기에 해당하는 경우 이러한 특성과 명령어가 필요합니다.

기기에 해당하는 경우 이러한 특성을 사용하는 것이 좋습니다. 그러나 기존의 제품 기능과 가장 잘 일치하도록 사용 가능한 모든 특성에서 자유롭게 조합할 수 있습니다.

품질 요구사항

  • 지연 시간: 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"
        }
      }
    ]
  }
}

기기 오류

오류 및 예외의 전체 목록을 참조하세요.

경보 시스템 예외 보고

시스템 경보 시스템을 설정하거나 해제하려고 하면 StatusReport 특성을 통해 보고하는 예외 코드를 통해 추가 컨텍스트를 제공할 수 있습니다. 예외는 차단 또는 비차단으로 보고될 수 있습니다.

  • '성공' 상태로 보고된 비차단 예외에서는 예외가 설정되어 경보 시스템을 설정하거나 해제할 수 없음을 나타냅니다.
  • '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"
          }
        }]
      }]
    }
  }]
}
응답 2
{
  "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 챌린지로 응답해야 합니다.

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