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

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

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

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

Обзор

Важным применением API является отображение элементов мультимедиа, резервные копии которых пользователь сделал в Google Photos. Можно вывести список элементов из определенного альбома или из всей библиотеки пользователя (представление по умолчанию в приложении Google Фото).

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

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

Внимание: не кэшируйте фотографии и видео пользователей. Вместо этого сохраните id медиа-элемента и снова запросите его данные, когда они вам понадобятся. Изображения могут измениться, а срок действия прямого доступа через baseUrl истекает через 60 минут. Дополнительные сведения см. в разделе Доступ к элементам мультимедиа .

Список альбомов

Вы можете получить список альбомов пользователя, используя 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"
}

Джава

try {
  // Make a request to list all albums in the user's library
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums();

  for (Album album : response.iterateAll()) {
    // Get some properties of an album
    String id = album.getId();
    String title = album.getTitle();
    String productUrl = album.getProductUrl();
    String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl();
    // The cover photo media item id field may be empty
    String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId();
    boolean isWritable = album.getIsWriteable();
    long mediaItemsCount = album.getMediaItemsCount();
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums in the user's library
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // Get some properties of an album
        $albumId = $album->getId();
        $title = $album->getTitle();
        $productUrl = $album->getProductUrl();
        $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl();
        // The cover photo media item id field may be empty
        $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId();
        $isWriteable = $album->getIsWriteable();
        $totalMediaItems = $album->getTotalMediaItems();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

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

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

Альбомы, которые были созданы в учетной записи пользователя или добавлены в учетную запись пользователя и к которым предоставлен общий доступ в вашем приложении, включают дополнительное свойство shareInfo . Дополнительные сведения см. в разделе Общий доступ к медиафайлам .

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

• Кто создал альбом.
• Если это общее или нет.
• Какие области действия одобрил пользователь.

Этот флаг может измениться, если изменится какой-либо из этих критериев. Дополнительные сведения см. в разделе Создание альбомов . Ответ также содержит nextPageToken . Для получения дополнительной информации см. Пагинация .

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

Вывод содержимого библиотеки

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

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

ОТДЫХ

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

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

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

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

Джава

try {
  // Make a request to list all media items in the user's library
  // Iterate over all the retrieved media items
  // Pagination is handled automatically
  ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems();
  for (MediaItem item : response.iterateAll()) {
    // Get some properties of a media item
    String id = item.getId();
    String description = item.getDescription();
    String mimeType = item.getMimeType();
    String productUrl = item.getProductUrl();
    String filename = item.getFilename();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in the user's library
    // Iterate over all the retrieved media items
    // Pagination is handled automatically
    $response = $photosLibraryClient->listMediaItems();
    foreach ($response->iterateAllElements() as $item) {
        // Get some properties of a media item
        /* @var $item \Google\Photos\Library\V1\MediaItem */
        $id = $item->getId();
        $description = $item->getDescription();
        $mimeType = $item->getMimeType();
        $productUrl = $item->getProductUrl();
        $filename = $item->getFilename();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Ответ содержит список медиа-элементов, упорядоченный от самых последних к последним. Дополнительные сведения см. в 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"
}

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

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

Джава

try {
  // Make a request to list all media items in an album
  // Provide the ID of the album as a parameter in the searchMediaItems call
  // Iterate over all the retrieved media items
  SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId);

  for (MediaItem item : response.iterateAll()) {
    // ...
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in an album
    // Provide the ID of the album as a parameter in the searchMediaItems call
    // Iterate over all the retrieved media items
    $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]);
    foreach ($response->iterateAllElements() as $item) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

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

Список общих альбомов

Вы можете получить список всех альбомов, которыми пользователь поделился или к которым был предоставлен доступ пользователю. Это похоже на вкладку «Общий доступ» в приложении Google Photos.

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

ОТДЫХ

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

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

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

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

Джава

try {
  // Make a request to list all albums that have been shared by the user
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums();

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been shared by the user
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listSharedAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

Альбомы, созданные и опубликованные вашим приложением, включают дополнительное свойство shareInfo . Дополнительные сведения см. в разделе Общий доступ к медиафайлам .

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

Вы можете перечислить альбомы, созданные вашим приложением, для excludeNonAppCreatedData установленного в true в следующих вызовах:

• albums.list
• sharedAlbums.list

ОТДЫХ

Вот запрос GET для вывода списка всех альбомов из библиотеки Google Фото пользователя, созданных только вашим приложением:

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Вот запрос GET для вывода списка всех общих альбомов из библиотеки Google Фото пользователя, созданных только вашим приложением:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Джава

try {
  // Make a request to list all albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

try {
  // Make a request to list all shared albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response =
      photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been created by your app
    $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

try {
    // Make a request to list all shared albums that have been created by your app
    $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

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

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

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

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

Примечание. Параметр pageSize имеет максимальное значение — может быть возвращено меньше результатов, чем запрошено.

Пример

Вы должны добавить 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 не должен использоваться в том же запросе.

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