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

Escopos de autorização necessários

Para listar conteúdo criado pelo app, é necessário ter a photoslibrary.readonly.appcreateddata do projeto. Para mais informações sobre escopos, consulte Autorização escopos.

Visão geral

A API Library permite listar e acessar itens de mídia que seu aplicativo criou.

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 pelo app

• Aplique filtros (data, categoria do conteúdo, mídia type) ao listar para restringir resultados

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

Listar o conteúdo da biblioteca e do álbum retorna uma lista de itens de mídia. Melhorias que fazem parte de um álbum não estão incluídas. 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 em Google Fotos e outros metadados relevantes. Para mais informações, consulte Acessar itens de mídia e mediaItems.

Listar álbuns criados por apps

Você pode listar álbuns que foram criados pelo seu aplicativo 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 do álbum, conforme mostrado em Listar conteúdo do álbum. Ela 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 um aberto pelo usuário.

O coverPhotoMediaItemId contém o item de mídia ID que representa a capa. foto deste álbum. Para acessar esta imagem de capa, use coverPhotoBaseUrl. Não use coverPhotoBaseUrl diretamente sem especificar parâmetros adicionais.

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

A resposta para álbuns vazios varia, já que mediaItemsCount e coverPhotoMediaItemId são definidos como 0 por padrão e são omitidos do REST resposta. coverPhotoBaseUrl aponta para um marcador de posição padrão imagem.

Listar o conteúdo da biblioteca criada pelo app

Você pode listar todos os itens de mídia da biblioteca do Google Fotos do usuário que foram criados pelo seu app. Isso exclui os itens arquivados e excluídos. Você pode listar itens de mídia com base em seu conteúdo, data e outras propriedades, aplicação de 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, ordenados do mais recente para o menos recente. Para saber mais, consulte mediaItems. Ela 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 álbuns. Se o albumId for inválido, será gerado um erro Bad Request. retornados. Se o ID for válido, mas o álbum não existir para a conta usuário, será retornado um erro Not Found. Para mais detalhes sobre erros, de desempenho,consulte as 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 uma 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 no 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, os métodos que retornam um grande número de resultados (como list) 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 estabelece um equilíbrio entre as o tamanho da resposta e a taxa de preenchimento. O tamanho máximo da página para o item de mídia pesquisar e listar solicitações é 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 sejam buscados no servidor.

Exemplo

Anexe o nextPageToken às solicitações subsequentes no parâmetro pageToken, conforme mostrado no exemplo abaixo. 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 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.