미디어 항목 나열 및 검색

사용자가 Picker API를 사용하여 미디어 항목을 선택하면 개발자는 해당 항목에 관한 정보를 검색하고 콘텐츠에 액세스할 수 있습니다. 이 가이드에서는 미디어 항목을 나열하고 검색하는 프로세스를 간략히 설명합니다.

시작하기 전에

  • 흐름 이해: 전체 사진 선택 프로세스의 개요는 Picker API 시작하기를 참고하세요.
  • 미디어 항목 선택 완료: 사용자가 세션에서 미디어 항목을 선택했는지 확인합니다. 자세한 내용은 세션 가이드를 참고하세요.
  • 필요한 승인 범위 검토: 세션을 사용하려면 photospicker.mediaitems.readonly 범위가 필요합니다. 범위에 관한 자세한 내용은 승인 범위를 참고하세요.

선택한 미디어 항목 목록

  1. mediaItems.list 엔드포인트 사용: https://photospicker.googleapis.com/v1/mediaItems에 GET 요청을 보내고 sessionId를 쿼리 매개변수로 제공합니다.

  2. 페이지 나누기 처리 (필요한 경우):

    사용자가 많은 항목을 선택하면 응답이 페이지로 나눠질 수 있습니다. 응답에서 nextPageToken를 사용하여 후속 결과 페이지를 검색합니다.

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

    • id: 미디어 항목의 고유 식별자입니다.
    • baseUrl: 다양한 해상도로 미디어 항목의 콘텐츠에 액세스하는 URL을 구성할 수 있는 기본 URL입니다.
    • mimeType: 미디어 항목의 MIME 유형입니다 (예: image/jpeg, video/mp4).

선택한 미디어 항목 가져오기

요청을 승인할 수 있는 https://www.googleapis.com/auth/photospicker.mediaitems.readonly 범위의 유효한 OAuth 2.0 액세스 토큰이 있는지 확인합니다.

  • 콘텐츠 URL 구성: PickedMediaItem 객체의 baseUrl를 사용합니다. 해상도 또는 파일 형식을 baseUrl에 추가합니다. 자세한 내용은 기본 URL 섹션을 참고하세요.

  • 콘텐츠 가져오기: 미디어 항목의 기본 URL에 GET 요청을 보냅니다. 응답에는 미디어 항목 (이미지 또는 동영상)의 바이트가 포함됩니다. 사용 가능한 다양한 baseURL 옵션이 있습니다.

기본 URL

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

Picker API의 경우:

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

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

Library API:

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

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

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

이미지 기본 URL

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

매개변수
w, h

설명

너비 w 및 높이 h 매개변수

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

예:

base-url=wmax-width-hmax-height

다음은 너비가 2048픽셀 이하이고 높이가 1024픽셀 이하인 미디어 항목을 표시하는 예입니다.

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

설명

자르기, c 매개변수

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

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

예:

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

이 예에서는 애플리케이션이 너비가 정확히 256픽셀, 높이가 256픽셀인 미디어 항목(예: 썸네일)을 표시합니다.

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

다음 예는 너비가 정확히 1280픽셀, 높이가 720픽셀이고 재생 버튼 오버레이가 포함되지 않은 동영상 썸네일을 표시합니다.

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

모션 사진 기본 URL

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

매개변수
dv

설명

모션 포토 미디어 항목의 동영상 요소를 검색하려면 동영상 기본 URL에서 다운로드할 때와 같이 dv 매개변수를 사용합니다.
w, h, c, d

설명

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