Просматривать медиафайлы и альбомы, созданные приложением

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

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

Обзор

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

Вот некоторые ключевые функции, связанные с получением списка медиаконтента:

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

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

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

REST

Вот пример такого запроса:

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.

REST

Вот пример такого запроса:

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

GET-запрос возвращает следующий ответ:

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

В ответе будет список медиафайлов, отсортированных по дате добавления (от новых к старым). Подробнее mediaItems… Также в нем есть nextPageToken, о котором подробнее рассказывается в разделе Разбивка на страницы.

Как посмотреть содержимое альбома

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

REST

Вот пример такого запроса:

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

Запрос POST возвращает следующий ответ:

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

Ответ содержит объект nextPageToken и список медиаобъектов. В отличие от запроса содержимого библиотеки, медиаобъекты возвращаются в том порядке, в котором они расположены в альбоме. Подробнее о параметре mediaItems и разбивке на страницы… Пользователь может изменить порядок в интерфейсе 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 не должен использоваться в том же запросе.