Method: mediaItems.search

사용자의 Google 포토 라이브러리에 있는 미디어 항목을 검색합니다. 설정된 필터가 없으면 사용자 라이브러리에 있는 모든 미디어 항목이 반환됩니다. 앨범이 설정되면 지정된 앨범의 모든 미디어 항목이 반환됩니다. 필터가 지정되면 사용자 라이브러리의 필터와 일치하는 미디어 항목이 나열됩니다. 앨범과 필터를 모두 설정하면 요청에 오류가 발생합니다.

HTTP 요청

POST https://photoslibrary.googleapis.com/v1/mediaItems:search

URL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (Filters)
  },
  "orderBy": string
}
필드
albumId

string

앨범의 식별자입니다. 채워지면 지정된 앨범의 모든 미디어 항목을 나열합니다. 필터와 함께 설정할 수 없습니다.
pageSize

integer

응답에서 반환할 미디어 항목의 최대 개수입니다. 지정된 수보다 적은 미디어 항목이 반환될 수 있습니다. 기본 pageSize는 25, 최댓값은 100입니다.
pageToken

string

결과의 다음 페이지를 가져오기 위한 연속 토큰 이를 요청에 추가하면 pageToken 뒤의 행이 반환됩니다. pageToken는 searchMediaItems 요청에 대한 응답의 nextPageToken 매개변수에서 반환된 값이어야 합니다.
filters

object (Filters)

요청에 적용할 필터입니다. albumId와 함께 설정할 수 없습니다.
orderBy

string

검색 결과의 정렬 순서를 지정하는 선택적 필드입니다. orderBy 필드는 dateFilter가 사용될 때만 작동합니다. 이 필드가 지정되지 않으면 결과가 creationTime부터 가장 오래된 것부터 표시됩니다. MediaMetadata.creation_time를 제공하면 검색 결과가 반대 순서로 표시됩니다. 즉, 오래된 항목이 먼저 표시되고 최근 날짜순으로 표시됩니다. 최신순으로 결과, 오래된 결과순을 표시하려면 MediaMetadata.creation_time desc와 같이 desc 인수를 포함합니다.

이 매개변수와 함께 사용할 수 있는 유일한 추가 필터는 includeArchivedMedia 및 excludeNonAppCreatedData입니다. 다른 필터는 지원되지 않습니다.

응답 본문

검색 매개변수와 일치하는 미디어 항목의 목록입니다.

성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "mediaItems": [
    {
      object (MediaItem)
    }
  ],
  "nextPageToken": string
}
필드
mediaItems[]

object (MediaItem)

출력 전용입니다. 검색 매개변수와 일치하는 미디어 항목 목록입니다.
nextPageToken

string

출력 전용입니다. 이 토큰을 사용하여 다음 미디어 항목 집합을 가져옵니다. 존재는 다음 요청에서 더 많은 미디어 항목을 사용할 수 있다는 신뢰할 수 있는 유일한 지표입니다.

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.readonly
  • https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
  • https://www.googleapis.com/auth/photoslibrary.readonly.originals

필터

미디어 항목 검색에 적용할 수 있는 필터입니다. 필터 옵션이 여러 개 지정된 경우 서로 AND로 취급됩니다.

JSON 표현 
{
  "dateFilter": {
    object (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
필드
dateFilter

object (DateFilter)

생성일을 기준으로 미디어 항목을 필터링합니다.
contentFilter

object (ContentFilter)

콘텐츠에 따라 미디어 항목을 필터링합니다.
mediaTypeFilter

object (MediaTypeFilter)

미디어 유형에 따라 미디어 항목을 필터링합니다.
featureFilter

object (FeatureFilter)

기능에 따라 미디어 항목을 필터링합니다.
includeArchivedMedia

boolean

설정하면 결과에 사용자가 보관처리한 미디어 항목이 포함됩니다. 기본값은 false입니다 (보관처리된 미디어 항목은 포함되지 않음).
excludeNonAppCreatedData

boolean

설정하면 결과에서 이 앱에서 만들지 않은 미디어 항목을 제외합니다. 기본값은 false입니다 (모든 미디어 항목이 반환됨). photoslibrary.readonly.appcreateddata 범위가 사용되는 경우 이 필드는 무시됩니다.

DateFilter

이 필터는 반환된 미디어에 허용되는 날짜 또는 기간을 정의합니다. 특정 날짜와 기간을 선택할 수 있습니다. 미디어 항목이 캡처된 날짜를 지정하는 메타데이터 없이 업로드된 미디어 항목은 날짜 필터를 사용하는 쿼리에 반환되지 않습니다. 이 경우 Google 포토 서버 업로드 시간은 대체로 사용되지 않습니다.

JSON 표현 
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
필드
dates[]

object (Date)

미디어 항목과 일치하는 날짜 목록입니다. 생성일. 요청당 최대 5개의 날짜를 포함할 수 있습니다.
ranges[]

object (DateRange)

미디어 항목과 일치하는 기간 목록 생성일. 요청당 최대 5개의 기간을 포함할 수 있습니다.

날짜

전체 달력 날짜를 나타냅니다. 월과 연도만 중요한 경우 day를 0으로 설정합니다(예: 2018년 12월 전체). 연도만 중요한 경우(예: 2018년 전체) day 및 month를 0으로 설정합니다. 기념일 또는 생일과 같이 일과 월만 중요한 경우 year를 0으로 설정합니다.

지원되지 않음: 모든 값을 0으로 설정하거나 month만 0으로 설정하거나 day와 year를 동시에 0으로 설정합니다.

JSON 표현 
{
  "year": integer,
  "month": integer,
  "day": integer
}
필드
year

integer

날짜의 연도입니다. 1~9999 사이여야 하며, 연도 없이 날짜를 지정하려면 0이어야 합니다.
month

integer

연도의 월입니다. 1~12 사이여야 하며, 월과 일 없이 연도를 지정하려면 0이어야 합니다.
day

integer

일. 1~31 사이의 값이어야 하며 연도와 월에 유효해야 합니다. 날짜가 중요하지 않은 연도/월을 지정하는 경우에는 0입니다.

DateRange

날짜 범위를 정의합니다. 두 날짜는 동일한 형식이어야 합니다. 자세한 내용은 Date를 참조하세요.

JSON 표현 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
필드
startDate

object (Date)

설명된 형식 중 하나로 지정된 시작일 (범위의 일부로 포함됨)입니다.
endDate

object (Date)

종료일 (범위의 일부로 포함)입니다. 시작일과 같은 형식으로 지정해야 합니다.

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 (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
필드
includedContentCategories[]

enum (ContentCategory)

미디어 항목 검색 결과에 포함될 카테고리 집합입니다. 세트의 항목은 OR 연산됩니다. 요청당 최대 10개의 includedContentCategories가 있습니다.
excludedContentCategories[]

enum (ContentCategory)

미디어 항목 검색 결과에 포함되지 않을 카테고리 집합입니다. 집합에 포함된 항목은 OR로 처리됩니다. 요청당 최대 10개의 excludedContentCategories가 있습니다.

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 (MediaType)
  ]
}
필드
mediaTypes[]

enum (MediaType)

포함할 미디어 항목의 유형입니다. 이 필드는 하나의 미디어 유형으로만 채워져야 합니다. 여러 미디어 유형을 지정하면 오류가 발생합니다.

MediaType

검색할 수 있는 미디어 유형 집합입니다.

열거형
ALL_MEDIA 필터가 적용되지 않은 것처럼 취급됩니다. 모든 미디어 유형이 포함됩니다.
VIDEO 동영상으로 간주되는 모든 미디어 항목입니다. 여기에는 사용자가 Google 포토 앱을 사용하여 만든 영화도 포함됩니다.
PHOTO 사진으로 간주되는 모든 미디어 항목 여기에는 .bmp, .gif, .ico, .jpg (및 기타 철자), .tiff, .webp 및 iOS 라이브 사진, Android 모션 사진, 파노라마, Photo Sphere와 같은 특수 사진 유형이 포함됩니다.

FeatureFilter

이 필터는 미디어 항목에 있어야 하는 기능을 정의합니다.

JSON 표현 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
필드
includedFeatures[]

enum (Feature)

미디어 항목 검색 결과에 포함될 기능 집합입니다. 집합에 포함된 항목은 OR로 처리되고 지정된 특성과 일치할 수 있습니다.

기능

필터링할 수 있는 기능의 집합입니다.

열거형
NONE 필터가 적용되지 않은 것처럼 처리됩니다. 모든 기능이 포함되어 있습니다.
FAVORITES 사용자가 Google 포토 앱에서 즐겨찾기로 표시한 미디어 항목입니다.