Escopos de autorização obrigatórios
A API Google Photos Library tem vários escopos usados para acessar itens de mídia e álbuns. Os itens de mídia retornados de várias chamadas são diferentes com base nos escopos solicitados pelo desenvolvedor.
O escopo photoslibrary.readonly
permite acesso a todos os itens de mídia na
biblioteca do usuário. O escopo photoslibrary.readonly.appcreateddata
permite acesso
apenas a itens de mídia criados pelo app. Para mais informações, consulte
Escopos de autorização.
Visão geral
Um uso importante da API é listar os itens de mídia que o usuário tiver armazenado em backup no Google Fotos. É possível listar os itens de um álbum específico ou de toda a biblioteca do usuário (a visualização padrão no app Google Fotos).
Você pode usar filtros para selecionar fotos que correspondam a uma data, categoria de conteúdo ou tipo de mídia especificado ao listar itens da biblioteca do usuário. Esse recurso não é compatível com itens de listas de álbuns.
Listar o conteúdo da biblioteca e do álbum retorna uma lista de itens de mídia.
Os enriquecimentos que fazem parte de um álbum
não são incluídos. Os itens de mídia descrevem uma foto, um vídeo ou outra mídia. Um
mediaItem
inclui um link direto para o item, um link para o item no
Google Fotos e outros metadados relevantes. Para mais informações, consulte
Acessar itens de mídia e
mediaItems
.
Álbuns da página "Detalhes do app"
Você pode recuperar uma lista dos álbuns do usuário usando albums.list.
REST
Confira um exemplo de solicitação:
GET https://photoslibrary.googleapis.com/v1/albums
A solicitação retorna o seguinte resultado:
{ "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" }
Java
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 }
Cada álbum retornado tem um ID que pode ser usado para recuperar o conteúdo do álbum, conforme mostrado em Como listar o conteúdo do álbum. Ele também inclui o título e o número de itens de mídia que ele contém.
O productUrl
aponta para o álbum no Google Fotos que pode ser aberto pelo usuário.
O coverPhotoMediaItemId
contém o ID do item
de mídia que
representa a foto da capa desse álbum. Para acessar essa imagem de capa, use
coverPhotoBaseUrl
. Não use coverPhotoBaseUrl
diretamente sem especificar outros parâmetros.
Álbuns que foram criados na conta do usuário ou adicionados a ela
e que seu app compartilhou incluem uma propriedade shareInfo
extra.
Veja mais detalhes em Compartilhar mídia.
Os álbuns também podem ter uma flag isWriteable
para indicar se você pode criar itens
de mídia neles. O padrão dessa flag será false
se não for retornada. Ela
depende do acesso concedido ao aplicativo, incluindo o seguinte:
- Quem criou o álbum.
- Se foi compartilhada ou não.
- Os escopos aprovados pelo usuário.
Esse indicador poderá ser alterado se qualquer um desses critérios for alterado. Para mais detalhes, consulte
Criar álbuns. A
resposta também contém um nextPageToken
. Para mais informações, consulte
Paginação.
A resposta para álbuns vazios varia nisso, mediaItemsCount
e coverPhotoMediaItemId
são definidos como 0 por padrão e são omitidos da resposta REST. Observe também que coverPhotoBaseUrl
aponta para uma imagem de marcador de posição padrão.
Conteúdo da biblioteca de páginas de detalhes
É possível listar todos os itens de mídia da biblioteca do Google Fotos do usuário. Ela exclui os itens arquivados e excluídos. É possível listar itens de mídia com base no conteúdo, na data e em outras propriedades aplicando filtros. Se o usuário não tiver adicionado um item disponível na guia Compartilhamento do Google Fotos à biblioteca, esse item não será incluído nessa lista.
Para extrair um item de mídia, chame mediaItems.list.
REST
Confira um exemplo de solicitação:
GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
}
A solicitação GET retorna a seguinte resposta:
{ "mediaItems": [ ... ], "nextPageToken": "token-for-pagination" }
Java
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 }
A resposta contém uma lista de itens de mídia, ordenados do mais para o menos recente.
Para saber mais, consulte
mediaItems
. Ela também
contém um nextPageToken
, que é descrito em mais detalhes em
Paginação.
Como listar o conteúdo do álbum
Para listar todos os itens de mídia em um álbum, adicione o campo albumId
à sua solicitação de pesquisa. Para mais informações sobre o albumId
, consulte Como listar
álbuns e Como listar álbuns compartilhados. Se albumId
for inválido, um erro Bad Request
será retornado. Se o ID for válido, mas o álbum não existir para o usuário autenticado, um erro Not Found
será retornado. Para mais detalhes sobre o tratamento de erros,consulte Dicas
de desempenho e Práticas
recomendadas.
REST
Confira um exemplo de solicitação:
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"albumId": "album-id"
}
A solicitação POST retorna a seguinte resposta:
{ "mediaItems": [ ... ], "nextPageToken": "token-for-pagination" }
Java
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 }
A resposta contém um nextPageToken
e a lista de itens de mídia. Ao contrário da
listagem do conteúdo da biblioteca, os itens de mídia são retornados pela ordem no
álbum. Para mais detalhes, consulte
mediaItems
e Paginação. O usuário pode editar o pedido na interface do Google Fotos.
Se a albumId
estiver definida, não será possível aplicar um filtro ao listar o conteúdo do álbum.
Isso resulta em um erro Bad Request
.
Como listar álbuns compartilhados
É possível recuperar uma lista de todos os álbuns que o usuário compartilhou ou que foram compartilhados com um usuário. Ela é parecida com a guia "Compartilhar" do app Google Fotos.
Os álbuns compartilhados que o usuário adicionou à biblioteca do Google Fotos também são retornados na chamada de listagem de álbuns. Faça a seguinte chamada para listar álbuns compartilhados usando a API Library:
REST
Confira um exemplo de solicitação:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
A solicitação retorna o seguinte resultado:
{ "sharedAlbums": [...] "nextPageToken": "token-for-pagination" }
Java
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 }
Uma lista de álbuns está incluída no sharedAlbums
. Para mais informações, consulte Como listar álbuns. A resposta também contém um nextPageToken
.
Para mais informações, consulte Paginação.
Os álbuns que seu app criou e compartilhou incluem uma propriedade shareInfo
extra. Para mais detalhes, consulte Compartilhar
mídia.
Álbuns criados pelo app da página de detalhes
É possível listar álbuns criados pelo app com
excludeNonAppCreatedData
definido como true
nas seguintes chamadas:
REST
Esta é uma solicitação GET para listar todos os álbuns da biblioteca do Google Fotos do usuário criados apenas pelo seu app:
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Esta é uma solicitação GET para listar todos os álbuns compartilhados da biblioteca do Google Fotos do usuário criados apenas pelo seu app:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Java
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 }
Paginação para REST
Para melhorar o desempenho, métodos que retornam um grande número de resultados (como métodos de lista) podem paginar a resposta. O número máximo de resultados em cada página é fornecido pelo parâmetro pageSize
.
Para chamadas para mediaItems:search
e mediaItems:list
, o tamanho de página padrão é de 25 itens. Recomendamos esse tamanho de página porque ele atinge um equilíbrio entre o tamanho da resposta e a taxa de preenchimento. O tamanho máximo da página para pesquisas de
itens de mídia e solicitações de lista é de 100 itens.
O tamanho de página padrão e recomendado para a listagem de álbuns é de 20 álbuns, com um máximo de 50.
Quando o número de resultados disponíveis é maior que o tamanho da página, a resposta
inclui um nextPageToken
, que indica ao aplicativo que há
mais resultados a serem buscados no servidor.
Exemplo
Você precisa anexar o nextPageToken
às solicitações subsequentes no parâmetro
pageToken
, conforme mostrado no exemplo a seguir. Especifique pageToken
com outros parâmetros necessários para a operação, no corpo da solicitação ou como um parâmetro de consulta.
Solicitação no 1
{ "pageSize": "5", "filters": { … } }
Resposta 1
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Solicitação no 2
{ "pageSize": "5", "filters": { … }, "pageToken": "page-token" }
Resposta 2
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Continue esse padrão até que não haja mais objetos nextPageToken
.
O nextPageToken
só é válido para a mesma solicitação. Se algum parâmetro for
alterado, um nextPageToken
usado anteriormente não poderá ser usado na mesma solicitação.