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를 제공하면 검색 결과가 가장 오래된 항목부터 가장 최근 항목까지 반대 순서로 표시됩니다. 최신 결과부터 오래된 결과 순으로 표시하려면 다음과 같이 desc 인수를 포함합니다. MediaMetadata.creation_time 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 모션 사진, 파노라마, 비행 사진과 같은 특수 사진 유형이 포함됩니다.

FeatureFilter

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

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

enum (Feature)

미디어 항목 검색 결과에 포함할 기능 집합입니다. 세트의 항목은 OR 연산을 거치며 지정된 지형지물과 일치할 수 있습니다.

기능

필터링할 수 있는 지형지물 집합입니다.

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