Требуемые области авторизации
API библиотеки Google Фото содержит несколько областей, используемых для доступа к элементам мультимедиа и альбомам. Медиа-элементы, возвращаемые из различных вызовов, различаются в зависимости от того, какие области были запрошены разработчиком.
Область photoslibrary.readonly
обеспечивает доступ ко всем элементам мультимедиа в библиотеке пользователя. Область photoslibrary.readonly.appcreateddata
разрешает доступ только к элементам мультимедиа, созданным приложением. Дополнительные сведения см. в разделе Области авторизации .
Доступные фильтры
Вы можете выполнить поиск в библиотеке пользователя по определенным типам носителей. Например, вам могут потребоваться только предметы с изображением животных, выпущенные в определенный день, или вы можете исключить фотографии квитанций. Вы можете исключить или включить определенные элементы, применив фильтры к списку альбома или библиотеки. Существует пять доступных фильтров на основе свойств медиа-элемента:
- Категории контента (
includedContentCategories
,excludedContentCategories
) - Даты и диапазоны дат (
dates
,ranges
) - Возможности (
featureFilter
) - Типы мультимедиа (
mediaTypeFilter
) - Архивное состояние (
includeArchivedMedia
)
Фильтры не следует использовать в запросе 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 | TIFF |
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()] );
Фильтры нескольких типов мультимедиа нельзя комбинировать.
Исключить данные, созданные не в приложении
Чтобы исключить элементы мультимедиа, которые не были созданы вашим приложением, вы можете установить фильтр excludeNonAppCreatedData
, как показано в следующем примере:
ОТДЫХ
{ "filters": { "excludeNonAppCreatedData": true } }
Ява
// Create a new Filters object that excludes media not created by your app Filters filters = Filters.newBuilder() .setExcludeNonAppCreatedData(true) .build(); // Specify the Filters object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a new Filters object that excludes media not created by your app $filtersBuilder = new FiltersBuilder(); $filtersBuilder->setExcludeNonAppCreatedData(true); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
Обратите внимание: если вы используете область .readonly.appcreateddata
, этот фильтр игнорируется.
Архивное состояние
Возможно, ваши пользователи заархивировали некоторые из своих фотографий. По умолчанию архивные фотографии не возвращаются при поиске. Чтобы включить заархивированные элементы, вы можете установить флаг в фильтре, как показано в следующем примере:
ОТДЫХ
{ "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 ] );