Поиск и применение фильтров

Требуемые области авторизации

Область photoslibrary.readonly обеспечивает доступ ко всем элементам мультимедиа в библиотеке пользователя.

Для поиска и применения фильтров к содержимому, созданному приложением, требуется область данных photoslibrary.readonly.appcreateddata . Дополнительные сведения об областях см. в разделе Области авторизации .

Доступные фильтры

Вы можете выполнить поиск в пользовательской библиотеке мультимедийных элементов, созданных приложением, для конкретных типов мультимедиа. Например, вам могут потребоваться только предметы с животными, датированные определенным днем, или вы можете исключить фотографии квитанций. Вы можете исключить или включить определенные элементы, применив фильтры к списку альбома или библиотеки. Существует пять доступных фильтров на основе свойств медиа-элемента:

Фильтры не следует использовать в запросе mediaItems.search , если установлен albumId . Если фильтр используется при заданном идентификаторе альбома, возвращается ошибка INVALID_ARGUMENT (400).

Результаты сортируются по времени создания медиа-элемента. Порядок сортировки можно изменить для запросов, использующих фильтры по дате.

Подождите некоторое время, чтобы вновь загруженные медиафайлы появились в результатах поиска. СМИ сразу же появляются в нефильтрованных результатах поиска.

Медиа-элементы, дата которых находится в будущем, не отображаются в фильтрованном поиске. Они появляются в нефильтрованном поиске и поиске по альбомам.

Применение фильтра

Чтобы применить фильтр, вызовите mediaItems.search и укажите свойство filter .

ОТДЫХ

Вот 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 .

ОТДЫХ 

{
  "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 :

ОТДЫХ 

{
  "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()]
);

Включение и исключение нескольких категорий

Вы можете включить некоторые категории и исключить другие. Следующий пример возвращает LANDSCAPES и LANDMARKS , но удаляет все медиа-элементы, содержащие PEOPLE или SELFIES :

ОТДЫХ 

{
  "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()]
);

Даты и диапазоны дат

Фильтры даты ограничивают дату возвращаемых результатов указанным набором дней. Существует два способа указать фильтр даты: даты или диапазоны. Даты и диапазоны можно использовать вместе. Возвращаются элементы мультимедиа, соответствующие любой дате или диапазону дат. При желании порядок сортировки результатов можно изменить.

Даты

Дата содержит год, месяц и день. Принимаются следующие форматы:

  • Год
  • Год, месяц
  • Год, месяц, день
  • Месяц, день
  • Месяц

Если компонент даты пуст или имеет нулевое значение, он рассматривается как подстановочный знак. Например, если вы установите день и месяц, но не год, вы запрашиваете элементы с этого дня и месяца любого года:

ОТДЫХ 

{
  "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()]
);

Диапазоны дат

Диапазоны дат обеспечивают большую гибкость, чем даты. Например, вместо добавления нескольких дат можно использовать диапазон дат, чтобы увидеть набор дней в месяце.

Диапазон дат имеет значения startDate и endDate , оба из которых должны быть установлены. Каждая дата в диапазоне имеет те же ограничения формата, что описаны в разделе Даты . Даты должны иметь одинаковый формат: если датой начала является год и месяц, датой окончания также должен быть год и месяц. Диапазоны применяются инклюзивно, даты начала и окончания включаются в примененный фильтр:

ОТДЫХ 

{
  "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()]
    );

Объединение дат и диапазонов дат

Вы можете использовать несколько дат и несколько диапазонов дат одновременно. Элементы, попадающие в любую из этих дат, включаются в результаты. Отдельные даты и диапазоны дат не обязательно должны соответствовать одному и тому же формату, однако даты начала и окончания отдельных диапазонов должны соответствовать следующему:

ОТДЫХ 

{
  "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 , чтобы возвращать только те мультимедийные элементы, которые были отмечены пользователем как избранные:

ОТДЫХ 

{
  "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 может быть любым из нескольких форматов изображений:

БМП JPG
гифка PNG
HEIC ТИФФ
ICO ВЕБП

Он также включает специальные типы фотографий, такие как живые фотографии iOS, движущиеся фотографии, панорамы, фотосферы и фотографии VR.

Видео

VIDEO может быть различных видеоформатов:

3GP ММВ
3G2 МОД
АЧС МОВ
АВИ МП4
ДИВКС миль на галлон
М2Т МТС
М2ТС ТОД
М4В WMV
МКВ

VIDEO также включает специальные форматы видео, например: видео VR, замедленное видео и анимацию, созданную в приложении Google Фото.

В следующем примере фильтруется по PHOTO :

ОТДЫХ 

{
  "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()]
);

Фильтры нескольких типов мультимедиа нельзя комбинировать.

Архивное состояние

Возможно, ваши пользователи заархивировали некоторые из своих фотографий. По умолчанию архивные фотографии не возвращаются при поиске. Чтобы включить заархивированные элементы, вы можете установить флаг в фильтре, как показано в следующем примере:

ОТДЫХ 

{
  "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()]
);

Объединение фильтров

Различные виды фильтров можно комбинировать. Возвращаются только элементы, соответствующие всем запрошенным функциям.

При объединении фильтров ограничения форматирования для каждого типа фильтров такие же, как и при их индивидуальном использовании. В следующем примере возвращаются только фотографии, отнесенные к категории SPORT и датированные 2014 или 2010 годом:

ОТДЫХ 

{
  "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 год, показывая сначала самый старый, а последний — самый новый.

ОТДЫХ 

{
  "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
    ]
);