Получение списка мультимедийных элементов и альбомов, созданных приложением

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

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

Обзор

API библиотеки позволяет вам перечислять и получать доступ к элементам мультимедиа, созданным вашим приложением.

Некоторые ключевые особенности листинга медиа-элементов включают следующее:

• Список медиа-элементов из определенных альбомов, созданных приложением, или всей библиотеки, созданной приложением.

• Применяйте фильтры (дата, категория контента, тип носителя) при листинге, чтобы сузить результаты.

• Извлекайте объекты mediaItem с важными сведениями, такими как прямые ссылки и метаданные.

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

Получение списка альбомов, созданных приложением

Вы можете перечислить альбомы, созданные вашим приложением, с помощью albums.list .

GET https://photoslibrary.googleapis.com/v1/albums

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

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

productUrl указывает на альбом в Google Фото, который может открыть пользователь.

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

Ответ также содержит nextPageToken . Для получения дополнительной информации см. Пагинация .

Ответ для пустых альбомов различается тем, что mediaItemsCount и coverPhotoMediaItemId по умолчанию установлено значение 0, и они не включаются в ответ REST. Также обратите внимание, что coverPhotoBaseUrl указывает на изображение-заполнитель по умолчанию.

Получение списка содержимого библиотеки, созданной приложением

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

Чтобы вывести список элементов мультимедиа, вызовите mediaItems.list .

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

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

Ответ содержит список медиа-элементов, упорядоченный от самых последних к последним. Дополнительные сведения см. в mediaItems . Он также содержит nextPageToken , который более подробно описан в разделе «Разбиение на страницы» .

Список содержимого альбома

Чтобы перечислить все элементы мультимедиа в альбоме, добавьте поле albumId в свой поисковый запрос. Дополнительные сведения об albumId см. в разделе Список альбомов . Если albumId недействителен, возвращается ошибка Bad Request . Если идентификатор действителен, но альбом не существует для аутентифицированного пользователя, возвращается ошибка Not Found . Дополнительные сведения об обработке ошибок см. в разделах «Советы по производительности» и «Рекомендации» .

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

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

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

Если albumId установлен, вы не сможете применить фильтр при отображении содержимого альбома. Это приведет к ошибке Bad Request .

Пагинация для REST

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

Для вызовов mediaItems.search и mediaItems.list размер страницы по умолчанию составляет 25 элементов. Мы рекомендуем этот размер страницы, поскольку он обеспечивает баланс между размером ответа и скоростью заполнения. Максимальный размер страницы для поиска медиа-элементов и запросов списков составляет 100 элементов.

По умолчанию и рекомендуемый размер страницы при перечислении альбомов составляет 20 альбомов, максимум 50 альбомов.

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

Пример

Вы должны добавить nextPageToken к последующим запросам в параметре pageToken , как показано в следующем примере. Укажите pageToken вместе с другими параметрами, необходимыми для операции, либо в тексте запроса, либо в качестве параметра запроса.

Запрос №1

{
  "pageSize": "5",
  "filters": { … }
}

Ответ №1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Запрос №2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

Ответ №2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Продолжайте этот шаблон до тех пор, пока не останется объектов nextPageToken .

nextPageToken действителен только для одного и того же запроса. Если какие-либо параметры изменены, ранее использованный nextPageToken не должен использоваться в том же запросе.