Ambient API용 앱 구성

Ambient API를 사용하려면 Google API 콘솔에서 API를 사용 설정하고 OAuth 2.0 클라이언트 ID를 설정하여 프로젝트를 구성합니다. Ambient API는 TV 및 제한된 입력 기기 애플리케이션용 OAuth 2.0을 사용합니다.

애플리케이션은 Ambient API 사용자를 대신하여 Ambient API와 상호작용합니다. 사용자는 OAuth 2.0 프로토콜을 사용하여 이러한 API 요청을 승인합니다.

OAuth 2.0 클라이언트 ID를 사용하면 애플리케이션 사용자가 로그인하고 인증하여 Ambient API를 사용할 수 있습니다. Ambient API는 서비스 계정을 지원하지 않습니다. 이러한 API를 사용하려면 사용자가 유효한 Google 계정에 로그인해야 합니다.

앱 구성

먼저 API를 사용 설정한 다음 OAuth 2.0 클라이언트 ID를 요청합니다.

API 사용 설정

Ambient API를 사용하려면 먼저 프로젝트에서 사용 설정해야 합니다.

Google API 콘솔로 이동합니다.
메뉴 바에서 프로젝트를 선택하거나 새 프로젝트를 만듭니다.
Google 포토 API 중 하나를 열려면 탐색 메뉴에서 API 및 서비스 > 라이브러리를 선택합니다.
'Ambient API'를 검색합니다. Ambient API를 선택하고 사용 설정을 클릭합니다.

OAuth 2.0 클라이언트 ID 요청

다음 단계에 따라 OAuth 클라이언트 ID를 요청하고 애플리케이션에 맞게 구성합니다. Ambient API는 TV 및 제한된 입력 기기 애플리케이션용 OAuth 2.0을 사용합니다.

Google API 콘솔로 이동하여 프로젝트를 선택합니다.
메뉴에서 API 및 서비스 > 사용자 인증 정보를 선택합니다.
사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 > OAuth 클라이언트 ID를 클릭합니다.

참고: 새 프로젝트를 설정하는 경우 프로젝트의 동의 화면을 구성하라는 메시지가 표시될 수 있습니다.
애플리케이션 유형을 선택합니다. 이 예에서 애플리케이션 유형은 TV 및 입력 제한 기기입니다.
OAuth 2.0 클라이언트의 이름을 입력하고 만들기를 클릭합니다.
표시된 OAuth 클라이언트 대화상자에서 다음을 복사합니다.
- 클라이언트 ID
- 클라이언트 보안 비밀번호

앱은 이러한 값을 사용하여 사용 설정된 Google API에 액세스할 수 있습니다.

Ambient API에 액세스하는 공개 애플리케이션을 출시하려면 먼저 Google에서 앱을 검토해야 합니다. 애플리케이션을 테스트할 때 인증될 때까지 화면에 'Unverified app'(앱 미인증) 메시지가 표시됩니다.

앱을 구성했다면 시작할 준비가 된 것입니다. 다음 리소스를 살펴보거나 Ambient API의 간소화된 인증 흐름에 관해 자세히 알아보세요.

클라이언트 ID 변경

Google 포토 API를 통해 만든 리소스는 만들 때 사용한 원래 클라이언트 ID를 사용하여만 액세스하거나 수정할 수 있습니다. 예를 들어 Picker API에서 특정 클라이언트 ID로 session를 만들고 나중에 앱에서 해당 클라이언트 ID를 변경하면 앱은 이전 클라이언트 ID로 만든 모든 API 리소스에 액세스할 수 없게 됩니다.

신중하게 계획하고 사용 중인 포토 API에 적합한 클라이언트 ID 유형을 선택하세요. 액세스 문제를 방지하기 위해 절대적으로 필요한 경우에만 클라이언트 ID를 변경하세요.

Ambient API의 인증 흐름 간소화

표준 Ambient API 인증 흐름에서는 사용자가 다음 두 가지 QR 코드를 스캔해야 합니다.

먼저 Google 계정에 로그인합니다 (아직 로그인하지 않은 경우).
두 번째 링크는 Google 포토 계정에서 새로 만든 화면 보호 모드 기기에 연결되며 여기에서 표시할 미디어 항목을 선택할 수 있습니다.

간소화된 흐름을 사용하면 초기 인증 호출과 함께 추가 state 매개변수를 전달하여 사용자에게 단일 QR 코드를 제공할 수 있습니다.

제한된 입력 기기의 OAuth의 일부로 기기 및 사용자 코드를 요청할 때는 요청에 state 매개변수를 추가로 포함합니다. state 매개변수에 다음을 추가합니다.

매개변수

매개변수
`requestId`	`string` 필수입니다. 이 요청에 대해 클라이언트가 제공한 고유 식별자입니다. 이는 네트워크 장애 발생 시 리소스 중복을 완화하는 데 사용됩니다. 이 ID는 UUID (버전 4) 문자열 형식이어야 하며 다음 요구사항을 충족해야 합니다. 사용자에 관한 민감한 식별 정보가 포함되어서는 안 됩니다. 16진수 32자리로 구성되며 하이픈으로 구분된 5개 그룹으로 나뉘고 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' (또는 8-4-4-4-12) 형식여야 합니다.
`displayName`	`string` 선택사항입니다. 이 기기의 사용자 정의 표시 이름입니다. 이 정보는 Google 포토 앱 설정에서 사용자에게 표시되지만 이 API를 통해서만 수정할 수 있습니다. 유효한 표시 이름은 1~100자 (양 끝값 포함)여야 합니다.

requestId

string

필수입니다. 이 요청에 대해 클라이언트가 제공한 고유 식별자입니다. 이는 네트워크 장애 발생 시 리소스 중복을 완화하는 데 사용됩니다.

이 ID는 UUID (버전 4) 문자열 형식이어야 하며 다음 요구사항을 충족해야 합니다.

사용자에 관한 민감한 식별 정보가 포함되어서는 안 됩니다.
16진수 32자리로 구성되며 하이픈으로 구분된 5개 그룹으로 나뉘고 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' (또는 8-4-4-4-12) 형식여야 합니다.

displayName

string

선택사항입니다. 이 기기의 사용자 정의 표시 이름입니다.

이 정보는 Google 포토 앱 설정에서 사용자에게 표시되지만 이 API를 통해서만 수정할 수 있습니다.

유효한 표시 이름은 1~100자 (양 끝값 포함)여야 합니다.

예를 들어 다음 코드 블록을 참고하세요.

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

응답이 성공하면 user_code 및 verification_url가 포함되며, 이를 사용자에게 표시하면 (대부분 QR 코드로 표시) 사용자가 다른 기기에서 해당 위치로 이동할 수 있습니다. state 매개변수를 포함하면 나중에 Ambient API로 createDevice를 호출할 때 OAuth 흐름의 마지막 단계가 이 위치로 자동 리디렉션되므로 두 번째 QR 코드에서 settingsUri 표시를 건너뛸 수 있습니다.

자세한 내용은 아래의 자세한 설명을 참고하세요. 샘플 앱의 코드를 검토하여 Ambient API를 사용하는 제한된 입력 기기의 OAuth에 state 매개변수를 사용하는 예를 확인할 수도 있습니다.

간소화된 인증 흐름에 관한 세부정보

Ambient API의 간소화된 OAuth 흐름을 완전히 이해하려면 TV 및 제한된 입력 기기 애플리케이션용 OAuth 2.0 흐름과 표준 Ambient API 흐름을 모두 이해하는 것이 좋습니다. 다음은 각 흐름의 단계입니다.

TV 및 제한된 입력 기기 애플리케이션용 OAuth 2.0:

애플리케이션은 Google의 승인 서버에 요청을 전송하여 애플리케이션에서 액세스 권한을 요청할 범위를 식별합니다.
서버는 후속 단계에서 사용되는 여러 정보(예: 기기 코드, 사용자 코드)로 응답합니다.
사용자가 별도의 기기에서 입력하여 앱을 승인할 수 있는 정보를 표시합니다.
애플리케이션이 Google의 승인 서버를 폴링하여 사용자가 앱을 승인했는지 확인하기 시작합니다.
사용자가 더 풍부한 입력 기능이 있는 기기로 전환하고 웹브라우저를 실행한 다음 3단계에 표시된 URL로 이동하여 3단계에 표시된 코드를 입력합니다. 그러면 사용자는 애플리케이션에 대한 액세스 권한을 부여하거나 거부할 수 있습니다.
폴링 요청에 대한 다음 응답에는 앱이 사용자를 대신하여 요청을 승인하는 데 필요한 토큰이 포함됩니다. 사용자가 애플리케이션에 대한 액세스를 거부한 경우 응답에 토큰이 포함되지 않습니다.

Ambient API 흐름:

기존 OAuth 토큰을 확인하고 토큰을 새로고침하거나 새 토큰을 요청합니다.
OAuth 토큰을 가져온 후 새 기기를 만듭니다.
사용자에게 settingsUri를 표시하고 mediaSourcesSet가 true를 반환할 때까지 기기를 폴링하기 시작합니다.
사용자가 settingsUri로 이동하여 애플리케이션과 공유할 사진을 선택합니다.
mediaSourcesSet가 true를 반환하면 mediaItems 목록을 가져옵니다.
이제 슬라이드쇼나 기타 화면 보호 모드 환경을 시작할 수 있습니다.

두 흐름 모두 사용자에게 URL을 표시하고 사용자가 더 풍부한 입력 장치에서 해당 URL로 이동하는 단계가 포함됩니다. 초기 OAuth 호출에 state 매개변수를 포함하면 표시해야 하는 두 번째 URL을 방지할 수 있습니다.

이는 TV 및 제한된 입력 기기 애플리케이션용 OAuth 2.0 흐름의 마지막 단계에서 일반적으로 사용자를 '이제 기기로 돌아갈 수 있습니다'라는 페이지로 리디렉션하기 때문입니다. 상태 매개변수를 포함하면 흐름의 마지막 단계에서 settingsUri로 리디렉션하려고 시도합니다. 앱은 여전히 OAuth 토큰을 수신합니다. 이 토큰을 사용하여 동일한 requestId를 사용하여 createDevice를 호출해야 합니다. 동일한 ID를 가진 기기가 생성되면 초기 OAuth 흐름에 따라 사용자가 포토 앱 내의 리치 기기에서 올바른 페이지로 리디렉션됩니다.

다음 사항을 기억하세요.

인증에 문제가 있는 경우 settingsUri를 표시하는 것이 좋습니다.
사용자가 사진 선택을 업데이트하려는 경우와 같이 다른 경우에는 settingsUri를 계속 사용할 수 있습니다.