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