Listar o conteúdo da biblioteca, os álbuns e os itens de mídia

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.

Atenção: não armazene em cache fotos e vídeos do usuário. Em vez disso, armazene o item de mídia id e solicite os detalhes novamente quando precisar. As imagens podem mudar, e o acesso direto pela baseUrl expira após 60 minutos. Para mais informações, consulte Acessar itens de mídia.

Á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:

• albums.list
• sharedAlbums.list

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.

Observação :o parâmetro pageSize é o valor máximo. É possível retornar menos resultados do que o solicitado.

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.

Observação: a existência de nextPageToken é o único indicador se há ou não mais resultados a serem buscados do servidor. Não conte o número de resultados para determinar se você precisa usar o nextPageToken. Uma solicitação pode retornar menos resultados do que o solicitado no tamanho da página. Se um nextPageToken estiver presente, você poderá enviar uma solicitação de mais resultados após a solicitação inicial.