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 이후의 행이 반환됩니다. pageTokensearchMediaItems 요청에 대한 응답에서 nextPageToken 매개변수에 반환된 값이어야 합니다.

filters

object (Filters)

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

orderBy

string

검색 결과의 정렬 순서를 지정하는 선택적인 필드입니다. orderBy 필드는 dateFilter가 사용되는 경우에만 작동합니다. 이 필드를 지정하지 않으면 결과가 최신순으로, 오래된 결과부터 creationTime 기준으로 표시됩니다. MediaMetadata.creation_time을 제공하면 반대의 순서로 검색결과가 표시됩니다(오래된 항목 순으로 표시됨). 최신 결과부터 오래된 결과부터 오래된 결과까지 표시하려면 desc 인수를 다음과 같이 포함합니다. MediaMetadata.creation_time desc

이 매개변수에 사용할 수 있는 추가 필터는 includeArchivedMediaexcludeNonAppCreatedData뿐입니다. 다른 필터는 지원되지 않습니다.

응답 본문

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

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

JSON 표현
{
  "mediaItems": [
    {
      object (MediaItem)
    }
  ],
  "nextPageToken": string
}
입력란
mediaItems[]

object (MediaItem)

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

nextPageToken

string

출력 전용. 이 토큰을 사용하여 다음 미디어 항목 세트를 가져옵니다. 이 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": {
    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개의 기간을 포함할 수 있습니다.

날짜

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

지원되지 않음: 모든 값을 0으로 설정하거나, month만 0으로 설정하거나, dayyear를 동시에 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로 연결됩니다. 요청당 includedContentCategories는 최대 10개입니다.

excludedContentCategories[]

enum (ContentCategory)

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

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 Live Photos, Android 모션 사진, 파노라마, Photo Sphere)이 포함됩니다.

FeatureFilter

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

JSON 표현
{
  "includedFeatures": [
    enum (Feature)
  ]
}
입력란
includedFeatures[]

enum (Feature)

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

특성

필터링할 수 있는 특성 집합입니다.

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