- HTTP 요청
- 요청 본문
- 응답 본문
- 승인 범위
- 필터
- DateFilter
- 날짜
- DateRange
- ContentFilter
- ContentCategory
- MediaTypeFilter
- MediaType
- FeatureFilter
- 기능
- 실습
사용자의 Google 포토 라이브러리에서 미디어 항목을 검색합니다. 필터가 설정되지 않으면 사용자 라이브러리의 모든 미디어 항목이 반환됩니다. 앨범이 설정되면 지정된 앨범의 모든 미디어 항목이 반환됩니다. 필터가 지정되면 사용자 라이브러리의 필터와 일치하는 미디어 항목이 표시됩니다. 앨범과 필터를 모두 설정하는 경우 요청 시 오류가 발생합니다.
HTTP 요청
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
URL은 gRPC 트랜스코딩 구문을 사용합니다.
요청 본문
요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.
JSON 표현 |
---|
{
"albumId": string,
"pageSize": integer,
"pageToken": string,
"filters": {
object ( |
입력란 | |
---|---|
albumId |
앨범의 식별자입니다. 채워지면 지정된 앨범의 모든 미디어 항목을 나열합니다. 어떤 필터와 함께도 설정할 수 없습니다. |
pageSize |
응답에서 반환할 미디어 항목의 최대 개수입니다. 지정된 수보다 적은 미디어 항목이 반환될 수 있습니다. 기본 |
pageToken |
결과의 다음 페이지를 가져오는 연속 토큰입니다. 이를 요청에 추가하면 |
filters |
요청에 적용할 필터입니다. |
orderBy |
검색 결과의 정렬 순서를 지정하는 선택적인 필드입니다. 이 매개변수에 사용할 수 있는 추가 필터는 |
응답 본문
검색 매개변수와 일치하는 미디어 항목의 목록입니다.
성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.
JSON 표현 |
---|
{
"mediaItems": [
{
object ( |
입력란 | |
---|---|
mediaItems[] |
출력 전용. 검색 매개변수와 일치하는 미디어 항목의 목록입니다. |
nextPageToken |
출력 전용. 이 토큰을 사용하여 다음 미디어 항목 세트를 가져옵니다. 이 ID의 존재는 다음 요청에서 더 많은 미디어 항목을 사용할 수 있다는 신뢰할 수 있는 유일한 지표입니다. |
승인 범위
다음 OAuth 범위 중 하나가 필요합니다.
https://www.googleapis.com/auth/photoslibrary
https://www.googleapis.com/auth/photoslibrary.readonly
https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
필터
미디어 항목 검색에 적용할 수 있는 필터입니다. 여러 필터 옵션을 지정하면 서로 AND로 처리됩니다.
JSON 표현 |
---|
{ "dateFilter": { object ( |
입력란 | |
---|---|
dateFilter |
생성 날짜를 기준으로 미디어 항목을 필터링합니다. |
contentFilter |
콘텐츠에 따라 미디어 항목을 필터링합니다. |
mediaTypeFilter |
미디어 유형에 따라 미디어 항목을 필터링합니다. |
featureFilter |
기능에 따라 미디어 항목을 필터링합니다. |
includeArchivedMedia |
설정된 경우 결과에는 사용자가 보관처리한 미디어 항목이 포함됩니다. 기본값은 false입니다 (보관처리된 미디어 항목은 포함되지 않음). |
excludeNonAppCreatedData |
설정하면 이 앱에서 만들지 않은 미디어 항목이 결과에서 제외됩니다. 기본값은 false입니다 (모든 미디어 항목이 반환됨). photoslibrary.readonly.appcreateddata 범위가 사용되는 경우 이 필드는 무시됩니다. |
DateFilter
이 필터는 반환된 미디어에 허용되는 날짜 또는 기간을 정의합니다. 특정 날짜 및 기간 집합을 선택할 수 있습니다. 미디어 항목이 캡처된 날짜를 지정하는 메타데이터 없이 업로드된 미디어 항목은 날짜 필터를 사용하는 쿼리에서 반환되지 않습니다. 이 경우 Google 포토 서버 업로드 시간이 대체 값으로 사용되지 않습니다.
JSON 표현 |
---|
{ "dates": [ { object ( |
입력란 | |
---|---|
dates[] |
미디어 항목의 생성 날짜와 일치하는 날짜 목록입니다. 요청당 최대 5개의 날짜를 포함할 수 있습니다. |
ranges[] |
미디어 항목의 생성 날짜와 일치하는 기간 목록입니다. 요청당 최대 5개의 기간을 포함할 수 있습니다. |
날짜
전체 캘린더 날짜를 나타냅니다. 월과 연도만 중요한 경우(예: 2018년 12월 전체) day
를 0으로 설정합니다. 연도만 중요한 경우(예: 2018년 전체) day
및 month
를 0으로 설정합니다. 기념일이나 생일과 같이 일과 월만 중요한 경우 year
를 0으로 설정합니다.
지원되지 않음: 모든 값을 0으로 설정하거나, month
만 0으로 설정하거나, day
및 year
를 동시에 0으로 설정합니다.
JSON 표현 |
---|
{ "year": integer, "month": integer, "day": integer } |
입력란 | |
---|---|
year |
날짜의 연도입니다. 1에서 9999 사이의 값이어야 하며, 연도 없이 날짜를 지정하려면 0이어야 합니다. |
month |
월입니다. 1~12 사이의 값이어야 합니다. 월과 일 없이 연도를 지정하려면 0이어야 합니다. |
day |
일. 1~31 사이의 값이어야 하며 해당 연도와 월에 유효해야 합니다. 또는 일이 중요하지 않은 연도/월을 지정하는 경우에는 0이어야 합니다. |
DateRange
날짜 범위를 정의합니다. 두 날짜는 동일한 형식이어야 합니다. 자세한 내용은 Date
를 참고하세요.
JSON 표현 |
---|
{ "startDate": { object ( |
입력란 | |
---|---|
startDate |
설명된 형식 중 하나로 된 시작일 (범위의 일부로 포함)입니다. |
endDate |
종료일 (범위의 일부로 포함됨) 시작일과 같은 형식으로 지정해야 합니다. |
ContentFilter
이 필터를 사용하면 콘텐츠 유형에 따라 미디어 항목을 반환할 수 있습니다.
포함할 카테고리 목록 또는 제외할 카테고리 목록을 지정할 수 있습니다. 각 목록 내에서 카테고리는 OR로 결합됩니다.
콘텐츠 필터 includedContentCategories
: [c1, c2, c3] 은 (c1 OR c2 OR c3)을 포함하는 미디어 항목을 가져옵니다.
콘텐츠 필터 excludedContentCategories
: [c1, c2, c3] 은 (c1 OR c2 OR c3)을 포함하는 미디어 항목을 가져오지 않습니다.
다음 예와 같이 일부 카테고리를 포함하면서 다른 카테고리는 제외할 수도 있습니다. includedContentCategories
: [c1, c2], excludedContentCategories
: [c3, c4]
앞의 예는 (c1 OR c2) AND NOT (c3 OR c4)를 포함하는 미디어 항목을 가져옵니다. includedContentategories
에 표시되는 카테고리는 excludedContentCategories
에 표시되어서는 안 됩니다.
JSON 표현 |
---|
{ "includedContentCategories": [ enum ( |
입력란 | |
---|---|
includedContentCategories[] |
미디어 항목 검색결과에 포함될 카테고리 집합입니다. 세트의 항목은 OR로 연결됩니다. 요청당 |
excludedContentCategories[] |
미디어 항목 검색결과에 포함되지 않을 카테고리 집합입니다. 세트의 항목은 OR로 연결됩니다. 요청당 |
ContentCategory
필터링할 수 있는 사전 정의된 콘텐츠 카테고리의 모음입니다.
열거형 | |
---|---|
NONE |
기본 콘텐츠 카테고리입니다. 이 카테고리는 필터에 다른 카테고리가 사용될 때 무시됩니다. |
LANDSCAPES |
풍경이 포함된 미디어 항목입니다. |
RECEIPTS |
영수증이 포함된 미디어 항목입니다. |
CITYSCAPES |
도시 경관이 포함된 미디어 항목입니다. |
LANDMARKS |
랜드마크가 포함된 미디어 항목입니다. |
SELFIES |
셀카인 미디어 항목입니다. |
PEOPLE |
사용자가 포함된 미디어 항목입니다. |
PETS |
반려동물이 포함된 미디어 항목입니다. |
WEDDINGS |
결혼식 관련 미디어 항목입니다. |
BIRTHDAYS |
생일의 미디어 항목입니다. |
DOCUMENTS |
문서를 포함하는 미디어 항목입니다. |
TRAVEL |
여행 중에 촬영한 미디어 항목입니다. |
ANIMALS |
동물이 포함된 미디어 항목입니다. |
FOOD |
음식이 포함된 미디어 항목입니다. |
SPORT |
스포츠 이벤트의 미디어 항목입니다. |
NIGHT |
밤에 촬영한 미디어 항목입니다. |
PERFORMANCES |
공연의 미디어 항목입니다. |
WHITEBOARDS |
화이트보드가 포함된 미디어 항목입니다. |
SCREENSHOTS |
스크린샷인 미디어 항목입니다. |
UTILITY |
유틸리티로 간주되는 미디어 항목입니다. 여기에는 문서, 스크린샷, 화이트보드 등이 포함되나 이에 국한되지 않습니다. |
ARTS |
아트가 포함된 미디어 항목입니다. |
CRAFTS |
공예가 포함된 미디어 항목입니다. |
FASHION |
패션과 관련된 미디어 항목입니다. |
HOUSES |
집이 포함된 미디어 항목입니다. |
GARDENS |
정원이 포함된 미디어 항목입니다. |
FLOWERS |
꽃이 포함된 미디어 항목입니다. |
HOLIDAYS |
공휴일에 가져온 미디어 항목입니다. |
MediaTypeFilter
이 필터는 반환할 미디어 항목의 유형(예: 동영상 또는 사진)을 정의합니다. 하나의 미디어 유형만 지원됩니다.
JSON 표현 |
---|
{
"mediaTypes": [
enum ( |
입력란 | |
---|---|
mediaTypes[] |
포함할 미디어 항목의 유형입니다. 이 필드는 하나의 미디어 유형으로만 채워야 합니다. 여러 미디어 유형을 지정하면 오류가 발생합니다. |
MediaType
검색할 수 있는 미디어 유형 집합입니다.
열거형 | |
---|---|
ALL_MEDIA |
필터가 적용되지 않은 것처럼 처리됩니다. 모든 미디어 유형이 포함됩니다. |
VIDEO |
동영상으로 간주되는 모든 미디어 항목입니다. 여기에는 사용자가 Google 포토 앱을 사용하여 만든 영화도 포함됩니다. |
PHOTO |
사진으로 간주되는 모든 미디어 항목입니다. 여기에는 .bmp, .gif, .ico, .jpg(및 기타 철자), .tiff, .webp 및 특수 사진 유형(예: iOS Live Photos, Android 모션 사진, 파노라마, Photo Sphere)이 포함됩니다. |
FeatureFilter
이 필터는 미디어 항목에 있어야 하는 기능을 정의합니다.
JSON 표현 |
---|
{
"includedFeatures": [
enum ( |
입력란 | |
---|---|
includedFeatures[] |
미디어 항목 검색 결과에 포함될 기능 집합입니다. 세트의 항목은 OR로 연결되며 지정된 지형지물과 일치할 수 있습니다. |
특성
필터링할 수 있는 특성 집합입니다.
열거형 | |
---|---|
NONE |
필터가 적용되지 않은 것처럼 처리됩니다. 모든 기능이 포함되어 있습니다. |
FAVORITES |
사용자가 Google 포토 앱에서 즐겨찾기로 표시한 미디어 항목 |