Listar itens de mídia e álbuns criados pelo app

Escopos de autorização necessários

A listagem de conteúdo criado pelo app requer o escopo photoslibrary.readonly.appcreateddata. Para mais informações sobre escopos, consulte Escpos de autorização.

Visão geral

A API Library permite listar e acessar itens de mídia criados pelo seu app.

Alguns dos principais recursos para listar itens de mídia incluem:

• Listar itens de mídia de álbuns específicos criados pelo app ou de toda a biblioteca criada por ele

• Aplicar filtros (data, categoria de conteúdo, tipo de mídia) ao listar para restringir os resultados

• Recupere objetos mediaItem com detalhes essenciais, como links diretos e metadados.

A listagem do 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 outro tipo de 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.

Listar álbuns criados pelo app

Você pode listar álbuns que foram criados pelo seu app usando 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"
}

Cada álbum retornado tem um ID que pode ser usado para recuperar o conteúdo, conforme mostrado em Listar conteúdo do álbum. Ele também inclui o título e o número de itens de mídia que 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 o coverPhotoBaseUrl diretamente sem especificar outros parâmetros.

A resposta também contém um nextPageToken. Para mais informações, consulte Paginação.

A resposta para álbuns vazios varia porque mediaItemsCount e coverPhotoMediaItemId são definidos como 0 por padrão e omitidos da resposta REST. Além disso, coverPhotoBaseUrl aponta para uma imagem de marcador de posição padrão.

Listar o conteúdo da biblioteca criada pelo app

É possível listar todos os itens de mídia da biblioteca do Google Fotos do usuário que foram criados pelo seu app. Isso exclui 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.

Para listar itens de mídia, chame mediaItems.list.

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

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

A resposta contém uma lista de itens de mídia, ordenada do mais recente para o mais antigo. Para saber mais, consulte mediaItems. Ele também contém um nextPageToken, que é descrito em mais detalhes em Paginação.

Listar 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 albumId, consulte Listagem de álbuns. 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 processamento de erros, consulte Dicas de desempenho e Práticas recomendadas.

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"
}

A resposta contém um nextPageToken e a lista de itens de mídia. Ao contrário de listar o 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 albumId estiver definido, não será possível aplicar um filtro ao listar o conteúdo do álbum. Isso resulta em um erro Bad Request.

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 padrão da página é 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 solicitações de pesquisa e lista de itens de mídia é de 100 itens.

O tamanho de página padrão e recomendado ao listar álbuns é de 20 álbuns, com um máximo de 50 álbuns.

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 do servidor.

Exemplo

Anexe o nextPageToken às solicitações subsequentes no parâmetro pageToken, conforme mostrado no exemplo a seguir. Especifique o 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 é válido apenas para a mesma solicitação. Se algum parâmetro for alterado, um nextPageToken usado anteriormente não poderá ser usado na mesma solicitação.