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 должен быть значением, возвращаемым в параметре nextPageToken в ответе на запрос searchMediaItems .

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.readonly.appcreateddata

Фильтры

Фильтры, которые можно применять к поиску медиа-элементов. Если указано несколько параметров фильтра, они обрабатываются как И друг с другом.

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.

ДатаФильтр

Этот фильтр определяет разрешенные даты или диапазоны дат для возвращаемых носителей. Можно выбрать набор конкретных дат и набор диапазонов дат. Медиа-элементы, загруженные без метаданных с указанием даты захвата медиа-элемента, не будут возвращены в запросах с использованием фильтров по дате. В этом случае время загрузки сервера Google Фото не используется в качестве запасного варианта.

JSON-представление 
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
Поля
dates[]

object ( Date )

Список дат, соответствующих дате создания медиа-элемента. В один запрос можно включить максимум 5 дат.

ranges[]

object ( DateRange )

Список диапазонов дат, соответствующих дате создания элемента мультимедиа. В один запрос можно включить максимум 5 диапазонов дат.

Дата

Представляет целую календарную дату. Установите для day значение 0, если значимы только месяц и год, например, весь декабрь 2018 г. Установите day и month значение 0, если значим только год, например, весь 2018 г. Установите для 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, если указан год/месяц, когда день не имеет значения.

Диапазон дат

Определяет диапазон дат. Обе даты должны иметь одинаковый формат. Для получения дополнительной информации см. Date .

JSON-представление 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Поля
startDate

object ( Date )

Дата начала (включенная в диапазон) в одном из описанных форматов.

endDate

object ( Date )

Дата окончания (входит в диапазон). Она должна быть указана в том же формате, что и дата начала.

КонтентФильтр

Этот фильтр позволяет возвращать элементы мультимедиа в зависимости от типа контента.

Можно указать список категорий для включения и/или список категорий для исключения. Внутри каждого списка категории объединяются с помощью ИЛИ.

Фильтр содержимого 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 .

Категория контента

Это набор предопределенных категорий контента, по которым вы можете фильтровать.

Перечисления
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 Материалы СМИ, сделанные в праздничные дни.

МедиаТипФильтр

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

JSON-представление 
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
Поля
mediaTypes[]

enum ( MediaType )

Типы мультимедийных элементов, которые необходимо включить. Это поле должно быть заполнено только одним типом носителя. Если вы укажете несколько типов носителей, это приведет к ошибке.

Медиатип

Набор типов мультимедиа, по которым можно осуществлять поиск.

Перечисления
ALL_MEDIA Рассматривается так, как будто фильтры не применяются. Включены все типы носителей.
VIDEO Все медиа-элементы, которые считаются видео. Сюда также входят фильмы, созданные пользователем с помощью приложения Google Photos.
PHOTO Все медиа-элементы, которые считаются фотографиями. Сюда входят .bmp, .gif, .ico, .jpg (и другие варианты написания), .tiff, .webp и специальные типы фотографий, такие как живые фотографии iOS, движущиеся фотографии Android, панорамы и фотосферы.

FeatureFilter

Этот фильтр определяет функции, которыми должны обладать элементы мультимедиа.

JSON-представление 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
Поля
includedFeatures[]

enum ( Feature )

Набор функций, которые будут включены в результаты поиска медиа-элементов. Элементы в наборе объединены ИЛИ и могут соответствовать любому из указанных признаков.

Особенность

Набор функций, по которым можно фильтровать.

Перечисления
NONE Рассматривается так, как будто фильтры не применяются. Все функции включены.
FAVORITES Медиа-элементы, которые пользователь отметил как избранные в приложении Google Фото.
,

Ищет созданные приложением мультимедийные элементы в библиотеке 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 должен быть значением, возвращаемым в параметре nextPageToken в ответе на запрос searchMediaItems .

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.readonly.appcreateddata

Фильтры

Фильтры, которые можно применять к поиску медиа-элементов. Если указано несколько параметров фильтра, они обрабатываются как И друг с другом.

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.

ДатаФильтр

Этот фильтр определяет разрешенные даты или диапазоны дат для возвращаемых носителей. Можно выбрать набор конкретных дат и набор диапазонов дат. Медиа-элементы, загруженные без метаданных с указанием даты захвата медиа-элемента, не будут возвращены в запросах с использованием фильтров по дате. В этом случае время загрузки сервера Google Фото не используется в качестве запасного варианта.

JSON-представление 
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
Поля
dates[]

object ( Date )

Список дат, соответствующих дате создания медиа-элемента. В один запрос можно включить максимум 5 дат.

ranges[]

object ( DateRange )

Список диапазонов дат, соответствующих дате создания элемента мультимедиа. В один запрос можно включить максимум 5 диапазонов дат.

Дата

Представляет целую календарную дату. Установите для day значение 0, если значимы только месяц и год, например, весь декабрь 2018 г. Установите day и month значение 0, если значим только год, например, весь 2018 г. Установите для 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, если указан год/месяц, когда день не имеет значения.

Диапазон дат

Определяет диапазон дат. Обе даты должны иметь одинаковый формат. Для получения дополнительной информации см. Date .

JSON-представление 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Поля
startDate

object ( Date )

Дата начала (включенная в диапазон) в одном из описанных форматов.

endDate

object ( Date )

Дата окончания (входит в диапазон). Она должна быть указана в том же формате, что и дата начала.

КонтентФильтр

Этот фильтр позволяет возвращать элементы мультимедиа в зависимости от типа контента.

Можно указать список категорий для включения и/или список категорий для исключения. Внутри каждого списка категории объединяются с помощью ИЛИ.

Фильтр содержимого 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 .

Категория контента

Это набор предопределенных категорий контента, по которым вы можете фильтровать.

Перечисления
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 Материалы СМИ, снятые в праздничные дни.

МедиаТипФильтр

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

JSON-представление 
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
Поля
mediaTypes[]

enum ( MediaType )

Типы мультимедийных элементов, которые необходимо включить. Это поле должно быть заполнено только одним типом носителя. Если вы укажете несколько типов носителей, это приведет к ошибке.

Медиатип

Набор типов мультимедиа, по которым можно осуществлять поиск.

Перечисления
ALL_MEDIA Рассматривается так, как будто фильтры не применяются. Включены все типы носителей.
VIDEO Все медиа-элементы, которые считаются видео. Сюда также входят фильмы, созданные пользователем с помощью приложения Google Фото.
PHOTO Все медиа-элементы, которые считаются фотографиями. Сюда входят .bmp, .gif, .ico, .jpg (и другие варианты написания), .tiff, .webp и специальные типы фотографий, такие как живые фотографии iOS, движущиеся фотографии Android, панорамы и фотосферы.

FeatureFilter

Этот фильтр определяет функции, которыми должны обладать элементы мультимедиа.

JSON-представление 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
Поля
includedFeatures[]

enum ( Feature )

Набор функций, которые будут включены в результаты поиска медиа-элементов. Элементы в наборе объединены ИЛИ и могут соответствовать любому из указанных признаков.

Особенность

Набор функций, по которым можно фильтровать.

Перечисления
NONE Рассматривается так, как будто фильтры не применяются. Все функции включены.
FAVORITES Медиа-элементы, которые пользователь отметил как избранные в приложении Google Фото.