필터 검색 및 적용

필수 승인 범위

photoslibrary.readonly 범위를 사용하면 사용자 라이브러리로 이동합니다.

앱 생성 콘텐츠를 검색하고 필터를 적용하려면 photoslibrary.readonly.appcreateddata 범위. 범위에 대한 자세한 내용은 승인 범위를 참조하세요.

사용 가능 필터

앱에서 만든 미디어 항목의 사용자 라이브러리에서 특정 종류의 미디어를 검색할 수 있습니다. 예를 들어 특정 날짜의 동물 사진만 가져오거나 영수증 사진은 제외하고 싶을 수 있습니다. 앨범 또는 보관함 목록에 필터를 적용하여 특정 항목을 제외하거나 포함할 수 있습니다. 거기 미디어 항목 속성을 기준으로 5가지 필터를 사용할 수 있습니다.

albumId이 다음과 같은 경우 mediaItems.search 요청에서 필터를 사용하면 안 됩니다. 설정합니다. albumId가 설정된 경우 필터가 사용되면 INVALID_ARGUMENT 오류(400)가 반환됩니다.

결과는 미디어 항목 생성 시간에 따라 정렬됩니다. 정렬 순서 수정할 수 있습니다.

새로 업로드한 미디어가 검색에 표시될 때까지 약간의 시간이 소요됩니다. 미디어 필터링되지 않은 검색어에 즉시 표시됩니다.

날짜가 미래인 미디어 항목은 필터링된 검색결과에 표시되지 않습니다. 해당 항목은 필터링되지 않은 검색결과 및 앨범 검색에 표시됩니다.

필터 적용

필터를 적용하려면 다음을 호출합니다. mediaItems.searchfilter 속성을 지정합니다.

REST

다음은 POST 요청입니다.

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "filters": {
    ...
  }
}

POST 요청은 다음 응답을 반환합니다.

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

자바

try {
  // Create a new Filter object
  Filters filters = Filters.newBuilder()
      // .setContentFilter(...)
      // .setDateFilter(...)
      // ...
      .build();

  // Specify the Filter object in the searchMediaItems call
  SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
  for (MediaItem item : response.iterateAll()) {
    // ...
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $filtersBuilder = new FiltersBuilder();
    // $filtersBuilder->addIncludedCategory(...);
    // $filtersBuilder->addDate(...);
    // ...
    // Make a search call with the options set in the filters builder
    $response = $photosLibraryClient->searchMediaItems(
        ['filters' => $filtersBuilder->build()]
    );
    foreach ($response->iterateAllElements() as $element) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

자세한 내용은 라이브러리 콘텐츠, 앨범, 미디어 항목 표시를 참고하세요.

콘텐츠 카테고리

모든 미디어 항목이 처리되고 라벨이 지정됩니다. 특정 광고 단위를 다음 카테고리 중 하나에 해당합니다.

ANIMALS FASHION LANDMARKS RECEIPTS WEDDINGS
ARTS FLOWERS LANDSCAPES SCREENSHOTS WHITEBOARDS
BIRTHDAYS FOOD NIGHT SELFIES  
CITYSCAPES GARDENS PEOPLE SPORT  
CRAFTS HOLIDAYS PERFORMANCES TRAVEL  
DOCUMENTS HOUSES PETS UTILITY  

유틸리티 사진은 광범위한 미디어를 망라합니다. 이 카테고리에는 일반적으로 사용자가 캡처한 항목은 일부 작업을 수행하기 위해 캡처한 항목이며, 해당 태스크가 완료됩니다. 여기에는 문서, 영수증, 스크린샷, 스티커가 포함됩니다. 메모, 메뉴 및 기타 유사한 미디어 항목이 포함됩니다.

카테고리는 Google 포토 간혹 상품 라벨이 잘못 지정될 수 있으므로 콘텐츠 카테고리 필터의 정확성

카테고리 포함

여러 카테고리를 포함하면 카테고리가 포함됩니다. 요청당 최대 10개의 카테고리를 포함할 수 있습니다. 이 필터 예시는 LANDSCAPES 또는 LANDMARKS의 모든 항목을 반환합니다.

REST

{
  "filters": {
    "contentFilter": {
      "includedContentCategories": [
        "LANDSCAPES",
        "LANDMARKS"
      ]
    }
  }
}

자바

// Create a content filter that includes landmarks and landscapes
ContentFilter contentFilter = ContentFilter.newBuilder()
    .addIncludedContentCategories(ContentCategory.LANDMARKS)
    .addIncludedContentCategories(ContentCategory.LANDSCAPES)
    .build();
// Create a new Filters object
Filters filters = Filters.newBuilder()
    .setContentFilter(contentFilter)
    .build();
// Specify the Filter object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a content filter that includes landmarks and landscapes
$filtersBuilder = new FiltersBuilder();
$filtersBuilder->addIncludedCategory(ContentCategory::LANDMARKS);
$filtersBuilder->addIncludedCategory(ContentCategory::LANDSCAPES);
// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

카테고리 제외

제외된 카테고리와 일치하지 않는 미디어 항목만 표시됩니다. 포함된 카테고리와 마찬가지로 최대 10개의 카테고리를 제외할 수 있습니다. 요청당

이 필터는 PEOPLE 또는 SELFIES이 아닌 모든 항목을 반환합니다.

REST

{
  "filters": {
    "contentFilter": {
      "excludedContentCategories": [
        "PEOPLE",
        "SELFIES"
      ]
    }
  }
}

자바

// Create a content filter that excludes people and selfies
ContentFilter contentFilter = ContentFilter.newBuilder()
    .addExcludedContentCategories(ContentCategory.PEOPLE)
    .addExcludedContentCategories(ContentCategory.SELFIES)
    .build();
// Create a new Filters object
Filters filters = Filters.newBuilder()
    .setContentFilter(contentFilter)
    .build();
// Specify the Filter object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a content filter that excludes people and selfies
$filtersBuilder = new FiltersBuilder();
$filtersBuilder->addExcludedCategory(ContentCategory::PEOPLE);
$filtersBuilder->addExcludedCategory(ContentCategory::SELFIES);
// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

여러 카테고리 포함 및 제외

일부 카테고리는 포함하고 다른 카테고리는 제외할 수 있습니다. 다음 예를 참고하세요. LANDSCAPESLANDMARKS를 반환하지만 PEOPLE 또는 SELFIES인 경우:

REST

{
  "filters": {
    "contentFilter": {
      "includedContentCategories": [
        "LANDSCAPES",
        "LANDMARKS"
      ],
      "excludedContentCategories": [
        "PEOPLE",
        "SELFIES"
      ]
    }
  }
}

자바

// Create a content filter that excludes people and selfies and includes landmarks and landscapes
ContentFilter contentFilter = ContentFilter.newBuilder()
    .addIncludedContentCategories(ContentCategory.LANDSCAPES)
    .addIncludedContentCategories(ContentCategory.LANDMARKS)
    .addExcludedContentCategories(ContentCategory.PEOPLE)
    .addExcludedContentCategories(ContentCategory.SELFIES)
    .build();
// Create a new Filters object
Filters filters = Filters.newBuilder()
    .setContentFilter(contentFilter)
    .build();
// Specify the Filters object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a content filter that excludes people and selfies and includes landmarks and landscapes
$filtersBuilder = new FiltersBuilder();
$filtersBuilder->addIncludedCategory(ContentCategory::LANDMARKS);
$filtersBuilder->addIncludedCategory(ContentCategory::LANDSCAPES);
$filtersBuilder->addExcludedCategory(ContentCategory::PEOPLE);
$filtersBuilder->addExcludedCategory(ContentCategory::SELFIES);
// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

날짜 및 기간

날짜 필터는 반환된 결과의 날짜를 일 날짜 필터는 날짜 또는 범위, 두 가지 방법으로 지정할 수 있습니다. 날짜 및 범위를 함께 사용할 수 있습니다 날짜 또는 날짜와 일치하는 미디어 항목 반환됩니다. 원하는 경우 결과 정렬 순서 수정할 수 있습니다

날짜

날짜에는 연도, 월, 일이 포함됩니다. 다음 형식이 허용됩니다.

  • 연도
  • 년, 월
  • 년, 월, 일
  • 월, 일

날짜 구성요소가 비어 있거나 0으로 설정된 경우 와일드 카드. 예를 들어 일과 월은 설정하고 연도는 설정하지 않으면 해당 연도와 월의 항목을 요청하는 경우:

REST

{
  "filters": {
    "dateFilter": {
      "dates": [
        {
          "month": 2,
          "day": 15
        }
      ]
    }
  }
}

자바

// Create a new com.google.type.Date object using a builder
// Note that there are different valid combinations as described above
Date dayFebruary15 = Date.newBuilder()
    .setDay(15)
    .setMonth(2)
    .build();
// Create a new dateFilter. You can also set multiple dates here
DateFilter dateFilter = DateFilter.newBuilder()
    .addDates(dayFebruary15)
    .build();
// Create a new Filters object
Filters filters = Filters.newBuilder()
    .setDateFilter(dateFilter)
    .build();
// Specify the Filters object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a new Google\Type\Date object with a day and a month
// Note that there are different valid combinations as described above
$dateFebruary15 = new Date();
$dateFebruary15->setDay(15);
$dateFebruary15->setMonth(2);
$filtersBuilder = new FiltersBuilder();
// Add the date to the filter. You can also set multiple dates here
$filtersBuilder->addDate($dateFebruary15);
// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

기간

기간은 날짜보다 유연하게 설정할 수 있습니다. 예를 들어 여러 날짜를 사용한 경우 기간을 사용하면 한 달 안의 여러 날짜를 표시할 수 있습니다.

기간에 startDateendDate가 있으며 둘 다 설정해야 합니다. 각 에 설명된 것과 동일한 형식 제약 조건이 날짜. 날짜는 다음과 같은 형식이어야 합니다. 시작일이 연도와 월의 경우 종료일도 연도와 월이어야 합니다. 범위는 포괄적으로 적용되면 시작일과 종료일이 적용된 필터에 포함됩니다.

REST

{
  "filters": {
    "dateFilter": {
      "ranges": [
        {
          "startDate": {
            "year": 2014,
            "month": 6,
            "day": 12
          },
          "endDate": {
            "year": 2014,
            "month": 7,
            "day": 13
          }
        }
      ]
    }
  }
}

자바

// Create new com.google.type.Date objects for two dates
Date day2014June12 = Date.newBuilder()
    .setDay(12)
    .setMonth(6)
    .setYear(2014)
    .build();
Date day2014July13 = Date.newBuilder()
    .setDay(13)
    .setMonth(7)
    .setYear(2014)
    .build();
// Create a DateRange from these two dates
DateRange dateRange = DateRange.newBuilder()
    .setStartDate(day2014June12)
    .setEndDate(day2014July13)
    .build();
// Create a new dateFilter with the date range. You can also set multiple date ranges here
DateFilter dateFilter = DateFilter.newBuilder()
    .addRanges(dateRange)
    .build();
// Create a new Filters object
Filters filters = Filters.newBuilder()
    .setDateFilter(dateFilter)
    .build();
// Specify the Filters object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create two new Google\Type\Date objects
    $date2014June12 = new Date();
    $date2014June12->setDay(12);
    $date2014June12->setMonth(6);
    $date2014June12->setYear(2014);

    $date2014July13 = new Date();
    $date2014July13->setDay(13);
    $date2014July13->setMonth(7);
    $date2014July13->setYear(2014);

    // Add the two dates as a date range to the filter
    // You can also set multiple date ranges here
    $filtersBuilder = new FiltersBuilder();
    $filtersBuilder->addDateRange($date2014June12, $date2014July13);

    // Make a search call with the options set in the filters builder
    $response = $photosLibraryClient->searchMediaItems(
        ['filters' => $filtersBuilder->build()]
    );

날짜 및 기간 결합

여러 날짜와 기간을 동시에 사용할 수 있습니다. 이 기간에 해당하는 항목이 결과에 포함됩니다. 별도의 날짜 및 기간은 같은 형식을 따르지 않아도 되지만 개별 범위의 기능은 다음과 같습니다.

REST

{
  "filters": {
    "dateFilter": {
      "dates": [
        {
          "year": 2013
        },
        {
          "year": 2011,
          "month": 11
        }
      ],
      "ranges": [
        {
          "startDate": {
            "month": 1
          },
          "endDate": {
            "month": 3
          }
        },
        {
          "startDate": {
            "month": 3,
            "day": 24
          },
          "endDate": {
            "month": 5,
            "day": 2
          }
        }
      ]
    }
  }
}

자바

// Create a new com.google.type.Date object for the year 2013
Date day2013 = Date.newBuilder()
    .setYear(2013)
    .build();
// Create a new com.google.type.Date object for November 2011
Date day2011November = Date.newBuilder()
    .setMonth(11)
    .setYear(2011)
    .build();
// Create a date range for January to March
DateRange dateRangeJanuaryToMarch = DateRange.newBuilder()
    .setStartDate(Date.newBuilder().setMonth(1).build())
    .setEndDate(Date.newBuilder().setMonth(3).build())
    .build();
// Create a date range for March 24 to May 2
DateRange dateRangeMarch24toMay2 = DateRange.newBuilder()
    .setStartDate(Date.newBuilder().setMonth(3).setDay(24).build())
    .setEndDate(Date.newBuilder().setMonth(5).setDay(2).build())
    .build();
// Create a new dateFilter with the dates and date ranges
DateFilter dateFilter = DateFilter.newBuilder()
    .addDates(day2013)
    .addDates(day2011November)
    .addRanges(dateRangeJanuaryToMarch)
    .addRanges(dateRangeMarch24toMay2)
    .build();
// Create a new Filters object
Filters filters = Filters.newBuilder()
    .setDateFilter(dateFilter)
    .build();
// Specify the Filter object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a new Google\Type\Date object for the year 2013
$date2013 = new Date();
$date2013->setYear(2013);

// Create a new Google\Type\Date object for November 2011
$dateNovember2011 = new Date();
$dateNovember2011->setMonth(11);
$dateNovember2011->setYear(2011);

$filtersBuilder = new FiltersBuilder();

// Create a date range for January to March
$filtersBuilder->addDateRange((new Date())->setMonth(1),
    (new Date())->setMonth(3));

// Create a date range for March 24 to May 2
$filtersBuilder->addDateRange((new Date())->setMonth(3)->setDay(24),
    (new Date())->setMonth(5)->setDay(2));

$filtersBuilder->addDate($date2013);
$filtersBuilder->addDate($dateNovember2011);

// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

미디어 항목 기능

기능 필터는 특정 기능이 있는 항목으로 결과를 제한합니다. Google 포토 애플리케이션에서 즐겨찾기로 표시한 예입니다.

즐겨찾기

항목 FAVORITES개 기능을 FeatureFilter 를 호출하여 사용자가 즐겨찾기로 표시한 미디어 항목만 반환합니다.

REST

{
  "filters" : {
    "featureFilter": {
      "includedFeatures": [
        "FAVORITES"
      ]
    }
  }
}

자바

// Create a new FeatureFilter for favorite media items
FeatureFilter featureFilter = FeatureFilter.newBuilder()
    .addIncludedFeatures(Feature.FAVORITES)
    .build();
// Create a new Filters object
Filters filters = Filters.newBuilder()
    .setFeatureFilter(featureFilter)
    .build();
// Specify the Filters object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a new FeatureFilter for favorite media items
$filtersBuilder = new FiltersBuilder();
$filtersBuilder->addIncludedFeature(Feature::FAVORITES);

// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

미디어 유형

사진 또는 미디어 유형 중 하나로 검색결과를 제한할 수 있습니다. 동영상.

사진

PHOTO는 다음과 같은 여러 이미지 형식 중 하나일 수 있습니다.

BMP JPG
GIF PNG
HEIC TIFF
ICO WEBP

iOS Live Photos, 모션 사진, 파노라마, Photo Sphere, VR 사진이 포함됩니다.

동영상

VIDEO는 다양한 동영상 형식일 수 있습니다.

3GP MMV
3G2 MOD
ASF : 아시아 태평양 MOV
AVI MP4
DIVX MPG
M2T MTS
M2TS TOD
M4V 항공 WMV
MKV  

VIDEO에는 VR 동영상, Google 포토에서 만든 슬로 모션 동영상 및 애니메이션 애플리케이션입니다.

다음 예에서는 PHOTO를 기준으로 필터링합니다.

REST

{
  "filters": {
    "mediaTypeFilter": {
      "mediaTypes": [
        "PHOTO"
      ]
    }
  }
}

자바

// Create a new MediaTypeFilter for Photo media items
MediaTypeFilter mediaType = MediaTypeFilter.newBuilder()
    .addMediaTypes(MediaType.PHOTO)
    .build();
// Create a new Filters object
Filters filters = Filters.newBuilder()
    .setMediaTypeFilter(mediaType)
    .build();
// Specify the Filters object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a new MediaTypeFilter for Photo media items
$filtersBuilder = new FiltersBuilder();
$filtersBuilder->setMediaType(MediaType::PHOTO);

// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

여러 미디어 유형 필터를 결합할 수 없습니다.

보관처리됨 상태

사용자가 일부 사진을 보관처리했을 수 있습니다. 기본적으로 보관처리된 사진은 제외되지 않습니다. 보관처리된 항목을 포함하려면 필터를 적용할 수 있습니다.

REST

{
  "filters": {
    "includeArchivedMedia": true
  }
}

자바

// Create a new Filters object that includes archived media
Filters filters = Filters.newBuilder()
    .setIncludeArchivedMedia(true)
    .build();

// Specify the Filters object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a new Filters object that includes archived media
$filtersBuilder = new FiltersBuilder();
$filtersBuilder->setIncludeArchivedMedia(true);

// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

필터 결합

다양한 종류의 필터를 결합할 수 있습니다. 모든 항목과 일치하는 항목만 반환됩니다.

필터를 결합할 때 각 필터 유형의 형식 지정 제한사항은 개별적으로 사용할 때와 동일합니다. 다음 예에서는 사진만 2014년 또는 2010년에 SPORT로 분류되고 반환:

REST

{
  "filters": {
    "contentFilter": {
      "includedContentCategories": [
        "SPORT"
      ]
    },
    "dateFilter": {
      "dates": [
        {
          "year": 2014
        },
        {
          "year": 2010
        }
      ]
    },
    "mediaTypeFilter": {
      "mediaTypes": [
        "PHOTO"
      ]
    }
  }
}

자바

// Create a new ContentFilter that only includes SPORT items
ContentFilter contentFilter = ContentFilter.newBuilder()
    .addIncludedContentCategories(ContentCategory.SPORT)
    .build();
// Create a new media type filter that only includes PHOTO media items
MediaTypeFilter mediaTypeFilter = MediaTypeFilter.newBuilder()
    .addMediaTypes(MediaType.PHOTO)
    .build();
// Create a new DateFilter that only includes items from 2010 or 2014
Date year2014 = Date.newBuilder().setYear(2014).build();
Date year2010 = Date.newBuilder().setYear(2010).build();
DateFilter dateFilter = DateFilter.newBuilder()
    .addDates(year2010)
    .addDates(year2014)
    .build();
// Create a new Filters object combining these filters
Filters filters = Filters.newBuilder()
    .setDateFilter(dateFilter)
    .setMediaTypeFilter(mediaTypeFilter)
    .setContentFilter(contentFilter)
    .build();
// Specify the Filter object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a new ContentFilter
$filtersBuilder = new FiltersBuilder();
// Only include SPORT items
$filtersBuilder->addIncludedCategory(ContentCategory::SPORT);
// Only include PHOTO media items
$filtersBuilder->setMediaType(MediaType::PHOTO);
// Only include items from 2010 or 2014
$year2014 = new Date();
$year2014->setYear(2014);
$year2010 = new Date();
$year2010->setYear(2010);
$filtersBuilder->addDateRange($year2010, $year2014);

// Make a search call with the options set in the filters builder
// Filters have been combined in the filter builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

결과 정렬

날짜 필터를 사용하는 쿼리만 정렬할 수 있습니다.

정렬 옵션을 지정하지 않으면 내림차순으로 (최근 항목순)

다음 표에는 orderBy 매개변수에 지원되는 옵션이 나와 있습니다.

orderBy 매개변수
MediaMetadata.creation_time desc 미디어 항목을 내림차순으로 반환합니다(최신 항목 먼저).
MediaMetadata.creation_time 미디어 항목을 오름차순으로 반환 (오래된 항목 먼저)

다음 예는 2017의 모든 미디어 항목을 반환하며 가장 최근의 순으로 표시됩니다

REST

{
  "filters": {
    "dateFilter": {
      "dates": [
        {
          "year": 2017
        }
      ]
    }
  },
  "orderBy": "MediaMetadata.creation_time"
}

자바

// Create a new dateFilter for the year 2017.
DateFilter dateFilter = DateFilter.newBuilder()
        .addDates(Date.newBuilder().setYear(2017))
        .build();

// Create a new Filters object
Filters filters = Filters.newBuilder()
        .setDateFilter(dateFilter)
        .build();

// Sort results by oldest item first.
final OrderBy newestFirstOrder = OrderBy.MEDIAMETADATA_CREATION_TIME;

// Specify the filter and sort order in the searchMediaItems call.
SearchMediaItemsPagedResponse response
        = photosLibraryClient.searchMediaItems(filters, newestFirstOrder);

PHP

// Create a new dateFilter for the year 2017.
$filtersBuilder = new FiltersBuilder();
$filtersBuilder->addDate((new Date())->setYear(2017));

// Make a search call with the options set in the filters builder and sort
// the results by oldest item first.
$response = $photosLibraryClient->searchMediaItems(
    [
        'filters' => $filtersBuilder->build(),
        'orderBy' => OrderBy::MEDIAMETADATA_CREATION_TIME
    ]
);