이 가이드에서는 기기를 만들고, 관리하고, 삭제하는 방법을 설명합니다. 적절한 기기 관리는 원활한 사용자 환경을 조성하고 Ambient API를 효율적으로 사용하는 데 도움이 됩니다.
기기 만들기
사용자가 TV 및 제한된 입력 기기 애플리케이션용 OAuth 2.0 흐름을 사용하여 인증한 후 Google 포토 계정에서 기기를 만듭니다.
앱이 devices.create 메서드를 사용하여 기기를 만들면 Ambient API는 Google에서 생성한 id가 포함된 AmbientDevice 객체를 반환합니다. 이 id를 안전하게 저장하고 사용자와 연결합니다.
OAuth를 통한 간소화된 기기 생성
Ambient API는 사용자 인증과 동시에 기기를 만들 수 있는 간소화된 OAuth 흐름을 제공합니다. 초기 OAuth 요청에 state 매개변수를 추가로 전달하면 기기 생성 프로세스를 사용자의 로그인 흐름에 직접 연결하여 스캔해야 하는 QR 코드 수를 줄여 사용자 환경을 간소화할 수 있습니다.
자세한 내용과 예시는 Ambient API의 간소화된 인증 흐름 가이드를 참고하세요.
기기 이용 한도
애플리케이션은 사용자당 최대 100대의 기기를 만들 수 있습니다. 이 한도를 초과하면 API에서 RESOURCE_EXHAUSTED 오류를 반환합니다.
기기 관리
기기가 생성되고 사용자의 Google 포토 계정에 연결되면 수명 주기를 관리해야 할 수 있습니다.
기기 검색
특정 기기에 대한 정보를 검색하려면 고유한 id와 함께 devices.get 메서드를 사용합니다. 이는 mediaSourcesSet가 true인지와 같은 기기의 상태를 확인하는 데 유용합니다.
기기 업데이트
devices.patch 메서드를 사용하여 디스플레이 이름과 같은 기존 기기의 특정 속성을 업데이트할 수 있습니다. 이를 통해 사용자는 기기를 맞춤설정하고 Google 포토에서 더 쉽게 기기를 식별할 수 있습니다.
기기 삭제
적절한 정리 및 사용자 제어를 위해 기기를 삭제하는 전략을 구현합니다.
devices.delete 메서드를 사용하여 기기를 삭제할 수 있습니다.
기기 삭제 시 다음 시나리오를 고려하세요.
- 사용자 연결 해제: 사용자가 Google 포토 계정에서 애플리케이션의 연결을 해제하면 해당 기기를 삭제해야 합니다.
- 부모 기기 없는 기기:
id를 찾을 수 없지만 생성 중에 사용된requestId는 있는 경우devices.delete와 함께requestId를 사용하여 부모 기기 없는 기기를 삭제할 수 있습니다. 이렇게 하면 실수로 중복이 발생하는 것을 방지하고 사용자의 계정을 깔끔하게 유지할 수 있습니다.
중요 고려사항 및 권장사항
- 기기 수명 주기 및 사용자 승인: 기기 및 사용자 승인 토큰의 수명 주기를 관리해야 합니다. 기기가 활성 상태로 유지되는 기간과 기기가 비활성화되거나 토큰이 만료되는 경우 토큰 갱신 또는 재승인 처리 방법을 고려하세요.
- 오류 처리: 모든 기기 관련 API 호출에 강력한 오류 처리를 구현합니다. 다음과 같은 시나리오에 대비하세요.
NOT_FOUND: 기기가 없거나 사용자가 소유하지 않은 경우RESOURCE_EXHAUSTED: 기기 한도를 초과하는 경우ALREADY_EXISTS: 이미 존재하는requestId로 기기를 만들려고 하면
다음 단계
- 샘플 애플리케이션: 샘플 애플리케이션에는 기기를 만들고 응답 데이터를 사용하는 예가 포함되어 있습니다.
자세한 내용은
createDevice함수를 확인하세요. - 참조 문서: 사용 가능한 모든 메서드, 요청 및 응답 매개변수, 오류 코드에 관한 자세한 내용은 포괄적인 기기 참조 문서를 검토하세요.
- 미디어 항목 나열 및 검색: 기기를 만들고 관리한 후에는 기기에 표시할 미디어 항목을 나열하고 검색하는 방법을 알아보세요.