포토 보관함 또는 앨범의 콘텐츠를 나열을 호출한 후 애플리케이션은 반환된 미디어 항목을 저장하는 대신 미디어 항목의 ID를 저장해야 합니다. 이는 미디어 항목의 콘텐츠가 변경될 수 있고 일정 시간이 지나면 응답에 포함된 URL이 만료되기 때문입니다. 미디어 항목 ID는 사용자 라이브러리에 있는 사진이나 동영상과 같은 미디어 항목을 고유하게 식별합니다.
필수 승인 범위
앱에서 만든 미디어 항목에 액세스하려면 photoslibrary.readonly.appcreateddata 범위가 필요합니다. 범위에 관한 자세한 내용은 승인 범위를 참고하세요.
미디어 항목
mediaItem는 Google 포토 라이브러리에 업로드된 사진이나 동영상과 같은 미디어의 표현입니다. 이는 최상위 객체이며 속성은 기본 미디어 유형에 따라 다를 수 있습니다.
다음 표에는 mediaItem 속성이 나와 있습니다.
| 속성 | |
|---|---|
id |
객체를 식별하는 데 사용되는 영구적이고 안정적인 ID입니다. |
description |
Google 포토 내에 표시되는 미디어 항목의 설명입니다. |
baseUrl |
원시 바이트에 액세스하는 데 사용됩니다. 자세한 내용은 기본 URL을 참조하세요. |
productUrl |
Google 포토 내 이미지 링크입니다. 이 링크는 개발자가 열 수 없으며 사용자만 열 수 있습니다. URL이 라이브러리의 미디어 항목을 가리킵니다. URL이 앨범 검색에서 검색된 경우 앨범 내 항목을 가리킵니다. |
mimeType |
미디어 유형을 쉽게 식별하는 데 도움이 되는 미디어 항목의 유형입니다(예: image/jpg). |
filename |
Google 포토 앱에서 사용자에게 표시되는 미디어 항목의 파일 이름입니다 (항목의 정보 섹션 내). |
mediaMetadata |
미디어의 기본 유형(예: photo 또는 video)에 따라 다릅니다.
페이로드를 줄이기 위해 필드 마스크를 사용할 수 있습니다.
|
미디어 항목 가져오기
미디어 항목을 가져오려면 mediaItemId를 사용하여 mediaItems.get을 호출합니다. 요청은 단일 미디어 항목을 반환합니다.
mediaItem에는 ID, 설명, URL과 같은 속성이 포함됩니다. photo 또는 video 내의 추가 정보는 파일 내의 메타데이터를 기반으로 합니다. 일부 속성은 표시되지 않을 수 있습니다.
미디어 항목이 동영상인 경우 동영상 파일을 먼저 처리해야 합니다. mediaItem에는 mediaMetadata 내에 동영상 파일의 처리 상태를 설명하는 status 필드가 포함되어 있습니다. 새로 업로드된 파일은 사용하기 전에 먼저 PROCESSING 값으로 videoProcessingStatus를 반환한 다음 READY로 반환합니다. 동영상 미디어 항목의 baseUrl는 동영상이 처리될 때까지 사용할 수 없습니다.
REST
다음은 GET 요청입니다.
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
사진 미디어 항목의 응답은 다음과 같습니다. photo 속성에는 사진 항목의 메타데이터가 포함됩니다.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"photo": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"focalLength": "focal-length-of-the-camera-lens",
"apertureFNumber": "aperture-f-number-of-the-camera-lens",
"isoEquivalent": "iso-of-the-camera",
"exposureTime": "exposure-time-of-the-camera-aperture"
}
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
동영상 미디어 항목의 응답은 다음과 같습니다. video 속성에는 동영상 항목의 메타데이터가 포함됩니다.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"video": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"fps": "frame-rate-of-the-video",
"status": "READY"
},
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
여러 미디어 항목 가져오기
식별자를 사용하여 여러 미디어 항목을 검색하려면 mediaItemId를 사용하여 mediaItems.batchGet를 호출합니다.
요청은 요청에 제공된 미디어 항목 식별자의 순서대로 MediaItemResults 목록을 반환합니다. 각 결과에는 MediaItem 또는 오류가 있는 경우 Status가 포함됩니다.
한 번의 호출로 요청할 수 있는 최대 미디어 항목 수는 50개입니다. 미디어 항목 목록에는 중복 식별자가 포함되어선 안 되며 비워 둘 수 없습니다.
REST
다음은 미디어 항목의 액세스 성공 및 실패를 보여주는 GET 요청입니다. 각 미디어 항목 식별자를 요청의 일부로 새 mediaItemIds 쿼리 매개변수로 지정합니다.
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id Content-type: application/json Authorization: Bearer oauth2-token
GET 요청은 다음 응답을 반환합니다.
{
"mediaItemResults": [
{
"mediaItem": {
"id": "media-item-id",
...
}
},
{
"mediaItem": {
"id": "another-media-item-id",
...
}
},
{
"status": {
"code": 3,
"message": "Invalid media item ID."
}
}
]
}
기본 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 |
설명 너비, 사진이나 동영상 썸네일과 같은 이미지 미디어 항목에 액세스하려면 애플리케이션에 표시할 크기를 지정해야 합니다. 그래야 이미지의 가로세로 비율을 유지하면서 이러한 크기로 이미지를 조정할 수 있습니다. 이렇게 하려면 예와 같이 기본 URL을 필요한 크기와 연결합니다. 예: base-url=wmax-width-hmax-height 다음은 너비가 2048픽셀 이하이고 높이가 1024픽셀 이하인 미디어 항목을 표시하는 예입니다. https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
설명 자르기, 지정한 정확한 너비와 높이로 이미지를 자르려면 기본 URL을 필수 크기 (픽셀)는 [1, 16383] 범위여야 합니다. 이미지의 너비 또는 높이가 요청된 크기를 초과하면 이미지가 축소되고 잘립니다 (가로세로 비율 유지). 예: base-url=wmax-width-hmax-height-c 이 예에서는 애플리케이션이 너비가 정확히 256픽셀, 높이가 256픽셀인 미디어 항목(예: 썸네일)을 표시합니다. https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
설명 다운로드 위치 메타데이터를 제외한 모든 Exif 메타데이터를 유지하면서 이미지를 다운로드하려면 기본 URL을 예: base-url=d 이 예에서는 애플리케이션이 위치 메타데이터를 제외한 모든 메타데이터가 포함된 이미지를 다운로드합니다. https://lh3.googleusercontent.com/p/Az....XabC=d |
동영상 기본 URL
다음은 동영상 기본 URL과 함께 사용할 수 있는 옵션 목록입니다.
| 매개변수 | |
|---|---|
dv |
설명 동영상 dv 매개변수는 원본 동영상의 고화질 트랜스코딩 버전을 요청합니다. 이 매개변수는 w 및 h 매개변수와 호환되지 않습니다. 동영상 다운로드의 기본 URL이 바이트를 반환하는 데 최대 몇 초가 걸릴 수 있습니다. 이 매개변수를 사용하기 전에 미디어 항목의 예: base-url=dv 다음 예는 동영상의 바이트를 다운로드하는 방법을 보여줍니다. https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w, h, c, d |
설명 동영상의 썸네일에 액세스하려면 이미지 기본 URL 매개변수를 사용합니다. 기본적으로 모든 동영상 썸네일에는 재생 버튼 오버레이가 포함됩니다. 이 오버레이를 삭제하려면 -no 매개변수를 참고하세요. 예: 예시는 이미지 기본 URL 표를 참고하세요. |
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에서 다운로드할 때와 같이 |
w, h, c, d |
설명 모션 사진 미디어 항목의 사진 요소를 검색하려면 이미지 기본 URL의 형식을 사용합니다. |