일반
Q: Cloud-to-Cloud 처리 인프라는 어디에서 어떤 언어로 구현해야 하나요?
A: 최신 SSL (TLS) 및 OAuth 2.0을 지원하는 한 어떤 플랫폼과 언어로든 인프라를 구현할 수 있습니다. 신뢰성을 개선하고 실제 사용자 기기에서 실행할 때의 지연 시간을 줄이려면 인프라의 나머지 부분과 최대한 가깝게 배포하는 것이 좋습니다.
Q: 기기 ID는 고유해야 하나요?
A: ID는 고유해야 합니다. 서비스 전반에 고유 ID가 없는 경우 적어도 사용자별 수준에서 고유해야 합니다. 두 집 모두 동일한 사용자와 통합된 여러 집이 있는 사용자를 생각해 보세요. 한 집에서 조명을 켜도록 요청해도 다른 집에서 동일한 ID의 조명이 켜져서는 안 됩니다.
Q: 기기 이름은 고유해야 하나요?
A: 이름은 고유하지 않아도 되지만, 시간이 지남에 따라 더 나은 사용자 환경을 위해 설정 후 잘못된 이름을 개선하는 것이 좋습니다.
다음은 간단한 이름 지정 가이드입니다.
- 이름은 사람들이 실제로 말할 수 있는 단어여야 합니다.
- 문자열의 하위 집합을 인식하므로 'acme color light'라고 말하면 'acme light'라고도 대답합니다.
- 제품의 설명이 포함된 이름과 하나 이상의 사용자 정의 이름을 모두 사용하는 것이 좋습니다.
- 사용자는 조명에 방 이름을 지정할 필요가 없습니다. 방이 이미 있으니까요. 방마다 고유한 이름을 지정해야 하지만 항상 복수형을 사용하여 모든 명령을 내릴 수 있습니다. 예를 들어 사무실 스콘스의 전구 두 개는 '북쪽 조명'과 '동쪽 조명'이지만 '조명'이라고만 명령해도 됩니다.
Q: 기기 상태는 얼마나 자주 업데이트되나요?
A: 일시적인 상태는 사용자가 시작한 작업인 QUERY 또는 EXECUTE 시 검색됩니다. 사용자가 '불이 켜져 있나요?'라고 묻거나 불을 밝히려는 경우 쿼리를 실행하여 현재 상태를 파악해야 합니다.
Q: 기기의 현재 상태로 Home Graph를 직접 업데이트할 수 있나요?
A: 예. Report State API 호출을 사용하세요.
계정 연결 및 OAuth
Q: 계정 연결이 필요한가요?
A: 예. 사용자의 기기를 제공업체의 클라우드 서비스에 연결하려면 계정 연결이 필요합니다.
Q: OAuth의 경우 15.213시간마다 액세스 토큰이 만료됩니다. 괜찮나요?
A: 예. 단, 10~20분 정도의 비교적 짧은 만료 시간으로 테스트하세요. OAuth 클라이언트는 필요에 따라 토큰을 새로고침해야 하며, 만료 시간이 짧은 토큰으로 테스트하면 제대로 작동하는지 확인할 수 있습니다.
인텐트
Q: SYNC는 언제 실행되나요?
A: 동기화는 OAuth 완료 직후 및 동기화 요청 호출 후 실행됩니다.
Q: SYNC가 작동하지 않는 이유는 무엇인가요?
A: 이 작업에 실패하는 데는 여러 가지 일반적인 이유가 있습니다.
잘못된 기기 유형을 보내고 있습니다.
- 예를 들어
action.devices.types.LIGHT가 예상되지만action.devices.types.Light가 전송됩니다.
- 예를 들어
지원되지 않는 기기 유형을 전송하고 있습니다.
- 예를 들어
action.devices.types.FLASHLIGHT를 전송하는 경우 Google에서 지원하지 않는 항목입니다.
- 예를 들어
잘못되거나 지원되지 않는 필드를 전송합니다.
- 예를 들어 사양에 없는 필드가 있습니다.
SYNC 응답에 다른 형식 문제가 있습니다.
- 대괄호를 확인하세요.
계정 연결 문제가 발생했습니다.
- SYNC 요청의 Auth 헤더에서 유효한 액세스 토큰을 수신하고 있는지 확인하세요.
SYNC 요청에 응답하는 데 시간이 너무 오래 걸립니다.
- SYNC 요청에 5초 이내에 응답하는지 확인합니다.
Q: '대기 중' 응답은 괜찮나요?
A: 기기를 실시간으로 사용할 수 있는 경우 대기 중 대신 성공/실패 응답을 사용하는 것이 좋습니다. '대기 중' 응답이 필요하다고 생각되면 문의해 주세요. 저전력 비실시간 기기의 경우 대기 중인 응답과 비동기 실행 모델이 필요할 수 있습니다.
테스트 및 제출
Q: 개발 클라우드 환경을 설정할 수 있나요?
A: 예, 출시되지 않은 클라우드 환경 및 구성을 테스트할 수 있습니다.
Q: Google Home 앱의 홈 컨트롤 섹션에 작업이 표시되지 않습니다. 어떻게 된 건가요?
A: 이 프로젝트의 개발자인지 확인합니다.
보고서 상태
Q: Report State를 구현하기 위한 기본 요건이 있나요?
A: 프로젝트는 Smart Home API를 사용하고, OAuth2를 지원하며, 보고할 상태가 있는 트레잇을 보유해야 합니다.
Q: 기기의 상태를 얼마나 자주 보고해야 하나요?
A: Google은 전환 및 종료 상태에 관심이 있습니다. 하지만 짧은 시간에 상태 변경이 여러 번 발생하는 경우 (예: 사용자가 1분에 냉장고를 열고 닫는 횟수가 3번이거나 조광기를 미는 경우) 보고된 최종 상태만 있으면 됩니다.
Q: Report State를 호출할 때 전체 기기 상태를 전송해야 하나요?
A: 부분 상태 업데이트는 지원되지 않으므로 Report State 호출에는 항상 업데이트된 특정 트레잇의 모든 데이터가 포함되어야 합니다. 두 트레잇이 불일치를 일으키는 경우 함께 다시 보고해야 합니다.
Q: Google에서 내 기기에 쿼리하여 상태를 가져올 수 있나요 (즉, 기기를 폴링할 수 있나요)?
A: 이는 권장되지 않는 대체 메커니즘입니다. 이러한 사용자를 위해 기기 폴링을 자주 사용해야 하는 경우 추가 부하가 얼마나 될지 보장할 수 없습니다. 이는 새로운 시각적 노출 영역에서 비롯된 필요입니다. 알 수 없는 로드 문제 외에도 사용자 환경이 저하됩니다. Report State는 플랫폼에 매우 중요하다고 생각합니다.
Q: 현재 어떤 트레잇이 보고서 상태를 지원하나요?
A: 상태가 연결된 모든 공개 트레잇이 지원됩니다. 기기의 온라인 상태 변경사항도 보고해야 합니다.
장면에는 상태가 없습니다. 하지만 기기의 상태가 변경될 수 있습니다. Google Home Graph의 기기에 변경 상태가 있는 경우 이를 다시 보고해야 합니다.
Q: Report State에는 타임스탬프를 전송해야 하나요?
A: 타임스탬프는 필요하지 않습니다. 전송된 마지막 상태가 이전 호출을 재정의합니다.
Q: 이미 쿼리 또는 실행에서 상태를 전송하고 있다면 상태를 별도로 보고해야 하나요?
A: Home Graph는 Report State를 통해 전송된 상태만 저장합니다. EXECUTE 및 QUERY 인텐트에 대한 응답으로 반환되는 상태는 사용자에게 음성으로 응답하는 데만 사용되며 저장되지 않습니다. 따라서 기기의 새 상태가 이미 EXECUTE 또는 QUERY 인텐트에 대한 응답으로 반환된 경우에도 Report State를 호출해야 합니다.
Q: 지정된 기한 내에 보고서 상태를 완전히 구현하지 않으면 어떤 결과가 초래되나요?
A: 이로 인해 Google Home app (GHA) 및 시각적 노출 영역과 같은 사용자 환경이 저하됩니다. 즉, 상태를 폴링하기 위해 많은 QUERY 인텐트가 전송되며, 이는 파트너 클라우드의 추가 부하에 상응하는지 보장할 수 없습니다.
Q: 보고서 상태 구현을 테스트하려면 어떻게 해야 하나요?
A: Home Graph에 저장된 현재 기기 상태를 보여주는 셀프서비스 테스트 도구인 Home Graph Viewer를 사용하세요.
Q: Report State에 임의의 requestId를 사용할 수 있나요?
A: Report State이 EXECUTE 요청에 의해 트리거되는 경우 파트너는 EXECUTE 요청에서 수신한 것과 동일한 requestId를 사용하는 것이 좋습니다. 그렇지 않으면 임의의 requestId를 사용하면 됩니다.
Q: 사용자가 여러 기기를 보유하고 있고 그중 하나의 상태가 변경된 경우 모든 기기의 최신 상태를 보고해야 하나요?
A: 아니요. 특정 기기의 상태만 보고하면 됩니다.
권장사항
Q: 허용되는 지연 시간은 어느 정도인가요?
A: 200ms 미만이 이상적이며 2~5초도 괜찮습니다. 지연 시간이 5초 정도이면 Google에 문의하세요.
Q: 음성 제어 스피커가 오프라인 상태일 때 제대로 응답하도록 하려면 어떻게 해야 하나요?
A: 오프라인 기기의 오프라인 상태를 반환합니다. 이 오류의 TTS로 '지금은 사용할 수 없습니다'를 반환합니다. 자세한 내용은 오류 및 예외를 참고하세요.