미디어 항목 나열 및 검색

사용자가 Google 포토에서 주변 기기를 구성하고 미디어 소스를 선택하면 애플리케이션에서 이러한 미디어 항목을 나열하고 검색하여 표시할 수 있습니다.

시작하기 전에

  • 기기 설정 확인: 사용자를 위해 기기를 만들고 구성했는지 확인합니다.
  • Ambient API 흐름 이해: Ambient API 흐름을 검토하여 전체 프로세스, 특히 mediaSourcesSet 폴링과 관련된 단계를 이해합니다.

mediaSourcesSet 설문조사

기기의 미디어 항목을 나열하려면 사용자가 Google 포토 앱 내에서 애플리케이션과 공유할 사진을 선택해야 합니다. 애플리케이션은 이 선택이 이루어진 시점을 확인하기 위해 기기를 폴링해야 합니다.

특정 deviceId에 대해 devices.get 메서드를 주기적으로 호출합니다. AmbientDevice 응답에서 mediaSourcesSet 필드를 모니터링합니다. 처음에는 false입니다. 사용자가 미디어 소스를 선택하면 이 필드가 true로 변경됩니다.

AmbientDevice 응답에는 폴링 빈도의 가이드라인으로 사용해야 하는 pollInterval이 포함된 pollingConfig이 포함됩니다.

미디어 항목 나열

기기의 mediaSourcesSet가 true이면 사용자가 선택한 미디어 항목을 가져오기 시작할 수 있습니다.

  1. mediaItems.list 엔드포인트 사용: https://photosambient.googleapis.com/v1/mediaItems에 GET 요청을 실행하여 경로에 deviceId을 제공합니다.

  2. 페이지로 나누기 처리 (필요한 경우): 대답이 페이지로 나뉠 수 있습니다. pageSize 매개변수를 사용하여 반환할 최대 항목 수를 지정하고 이전 응답의 pageToken를 사용하여 결과의 후속 페이지를 검색합니다.

  3. 미디어 항목 처리: 응답에는 선택된 각 미디어 항목을 나타내는 AmbientMediaItem 객체의 배열이 포함됩니다. 이러한 객체에는 다음과 같은 필수 세부정보가 포함됩니다.

    • id: 미디어 항목의 고유 식별자입니다.
    • creationTime: 미디어 항목이 생성된 타임스탬프입니다.
    • mediaFile: 실제 콘텐츠에 액세스하기 위한 세부정보가 포함된 객체입니다.

mediaFile 필드에는 baseUrl이 포함됩니다. 이 baseUrl는 다양한 해상도나 형식으로 미디어 항목의 콘텐츠에 액세스하는 URL을 구성하는 데 사용됩니다.

기본 URL

Google 포토 API의 기본 URL은 미디어 항목의 원시 바이트에 대한 액세스를 제공하므로 앱에서 이를 다운로드하거나 표시할 수 있습니다. 이러한 URL은 앨범을 나열하거나 (라이브러리 API) 미디어 항목에 액세스할 때 (라이브러리 및 선택기 API 모두) 응답에 포함됩니다. 베이스 URL이 제대로 작동하려면 추가 매개변수가 필요합니다.

Picker API의 경우:

모든 PickedMediaItem.mediaFile 객체에는 baseUrl가 포함됩니다.

기본 URL은 60분 동안 활성 상태로 유지되지만 사용자가 Google 계정 설정을 통해 앱의 권한을 취소하면 더 빨리 만료될 수 있습니다.

라이브러리 API:

기본 URL은 60분 동안 활성 상태로 유지됩니다.

다양한 기준 URL은 다음과 같습니다.

  • baseUrl: 사진, 동영상의 썸네일에 직접 액세스하거나 동영상 바이트를 다운로드합니다.
  • coverPhotoBaseUrl: 앨범의 커버 사진에 직접 액세스합니다.
  • profilePictureBaseUrl: mediaItem 소유자의 프로필 사진에 직접 액세스합니다.

이미지 기본 URL

이미지 기본 URL과 함께 사용할 수 있는 옵션 목록은 다음과 같습니다.

매개변수
w, h

설명

너비(w) 및 높이(h) 매개변수

사진이나 동영상 썸네일과 같은 이미지 미디어 항목에 액세스하려면 애플리케이션에 표시할 크기를 지정해야 합니다. 그래야 가로세로 비율을 유지하면서 이미지를 이러한 크기로 조정할 수 있습니다. 이렇게 하려면 예에 표시된 대로 기준 URL을 필요한 크기와 연결합니다.

예:

base-url=wmax-width-hmax-height

다음은 너비가 2048px을 초과하지 않고 높이가 1024px을 초과하지 않는 미디어 항목을 표시하는 예입니다.

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

설명

자르기, c 매개변수

지정한 정확한 너비와 높이 치수로 이미지를 자르려면 기본 URL을 선택적 -c 매개변수와 필수 w 및 h 매개변수와 연결합니다.

크기 (픽셀)는 [1, 16383] 범위에 있어야 합니다. 이미지의 너비 또는 높이가 요청된 크기를 초과하면 이미지가 축소되고 잘립니다 (가로세로 비율 유지).

예:

base-url=wmax-width-hmax-height-c

이 예에서 애플리케이션은 썸네일과 같이 너비가 정확히 256px이고 높이가 256px인 미디어 항목을 표시합니다.

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

설명

다운로드, d 매개변수

위치 메타데이터를 제외한 모든 Exif 메타데이터를 유지하면서 이미지를 다운로드하려면 기본 URL을 d 매개변수와 연결합니다.

예:

base-url=d

이 예에서 애플리케이션은 위치 메타데이터를 제외한 모든 메타데이터가 포함된 이미지를 다운로드합니다.

https://lh3.googleusercontent.com/p/Az....XabC=d

동영상 기본 URL

동영상 기본 URL과 함께 사용할 수 있는 옵션 목록은 다음과 같습니다.

매개변수
dv

설명

동영상 mediaItem의 바이트에 액세스하려면 baseUrl를 다운로드 동영상, dv 매개변수와 연결합니다.

dv 매개변수는 트랜스코딩된 고화질 원본 동영상을 요청합니다. 이 매개변수는 w 및 h 매개변수와 호환되지 않습니다.

동영상 다운로드의 기본 URL은 바이트를 반환하는 데 최대 몇 초가 걸릴 수 있습니다.

이 매개변수를 사용하기 전에 미디어 항목의 mediaMetadata.status 필드가 READY인지 확인하세요. 그렇지 않고 미디어 항목의 처리가 완료되지 않은 경우 오류가 발생할 수 있습니다.

예:

base-url=dv

다음 예시는 동영상의 바이트를 다운로드하는 방법을 보여줍니다.

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c, d

설명

동영상의 썸네일에 액세스하려면 이미지 기본 URL 매개변수 중 하나를 사용하세요.

기본적으로 모든 동영상 썸네일에는 재생 버튼 오버레이가 포함됩니다. 이 오버레이를 삭제하려면 -no 매개변수를 참고하세요.

예:

예는 이미지 기본 URL 표를 참고하세요.
no

설명

썸네일 오버레이 삭제, no 매개변수

재생 버튼 오버레이 없이 동영상의 썸네일을 가져오려면 기본 URL을 no 매개변수와 연결합니다.

no 매개변수는 이미지 기본 URL 매개변수 중 하나 이상과 함께 사용해야 합니다.

예:

base-url=wmax-width-hmax-height-no

다음 예에서는 너비가 정확히 1280px이고 높이가 720px인 동영상 썸네일을 표시하며 재생 버튼 오버레이는 포함되지 않습니다.

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

모션 사진 기준 URL

모션 사진에는 사진과 동영상 요소가 모두 포함되어 있습니다. 동작 사진 baseUrl 요청에는 이미지 기본 URL 또는 동영상 기본 URL의 매개변수를 사용할 수 있습니다.

매개변수
dv

설명

동작 사진 미디어 항목의 동영상 요소를 가져오려면 동영상 기본 URL에서 다운로드하는 것과 마찬가지로 dv 매개변수를 사용합니다.
w, h, c, d

설명

동작 사진 미디어 항목의 사진 요소를 가져오려면 이미지 기본 URL 형식을 사용합니다.

콘텐츠 정책 및 필터링

Google 포토는 TV나 디지털 디스플레이와 같은 공유 기기에 표시되는 이미지와 동영상에 기본적으로 표준 콘텐츠 필터링을 적용합니다. 이 필터는 다음과 같은 콘텐츠를 제외하여 시청 환경을 최적화하도록 설계되었습니다.

  • 기능 이미지 (예: 스크린샷, 문서, 영수증)
  • 대형 화면에서 렌더링이 제대로 되지 않을 수 있는 이미지 (예: 해상도가 매우 낮음, 흐림, 과도한 그레인)
  • 매우 개인적이거나 민감한 것으로 식별된 콘텐츠로, 공유 설정에서 일반적인 표시를 의도하지 않을 수 있습니다.

모든 콘텐츠 필터링은 자동화되어 있습니다. 사용자가 표시되는 콘텐츠를 더 잘 관리할 수 있도록 사용자가 주변 모드에 사용되는 미디어 소스를 수동으로 선택하고 업데이트할 수 있도록 허용할 수 있습니다.

다음 단계

  • 샘플 애플리케이션: Google의 샘플 애플리케이션에는 미디어 항목을 나열하고 검색하는 예가 포함되어 있습니다. 자세한 내용은 checkMediaSourcesSet 및 fetch_media_item_list 함수를 참고하세요.
  • 참조 문서: 사용 가능한 모든 메서드, 요청 및 응답 매개변수, 오류 코드에 관한 자세한 내용은 포괄적인 미디어 항목 참조 문서를 참고하세요.