Listar e recuperar itens de mídia

Depois que um usuário configurar o dispositivo de ambiente e selecionar fontes de mídia no Google Fotos, seu app poderá listar e recuperar esses itens de mídia para exibição.

Antes de começar

  • Verificar a configuração do dispositivo:confira se você criou e configurou um dispositivo para o usuário.
  • Entender o fluxo da API Ambient:analise o fluxo da API Ambient para entender o processo geral, especialmente a etapa que envolve a pesquisa de mediaSourcesSet.

Enquete para mediaSourcesSet

Antes de listar itens de mídia para um dispositivo, o usuário precisa ter selecionado as fotos que ele quer compartilhar com seu app no Google Fotos. O app precisa consultar o dispositivo para determinar quando essa seleção foi feita.

Chame periodicamente o método devices.get para o deviceId específico. Monitore o campo mediaSourcesSet na resposta AmbientDevice. Inicialmente, será false. Depois que o usuário escolher as fontes de mídia, esse campo vai mudar para true.

A resposta AmbientDevice inclui um pollingConfig com um pollInterval que você deve usar como orientação para a frequência de pesquisa.

Listar itens de mídia

Quando mediaSourcesSet for true para um dispositivo, você poderá começar a buscar os itens de mídia selecionados pelo usuário.

  1. Usar o endpoint mediaItems.list:faça uma solicitação GET para https://photosambient.googleapis.com/v1/mediaItems, fornecendo o deviceId no caminho.

  2. Processar a paginação (se necessário): a resposta pode ser paginada. Use o parâmetro pageSize para especificar o número máximo de itens a serem retornados e o pageToken de uma resposta anterior para recuperar as páginas de resultados seguintes.

  3. Processar os itens de mídia:a resposta vai conter uma matriz de objetos AmbientMediaItem, cada um representando um item de mídia selecionado. Esses objetos incluem detalhes essenciais, como:

    • id: o identificador exclusivo do item de mídia.
    • creationTime: o carimbo de data/hora em que o item de mídia foi criado.
    • mediaFile: um objeto que contém detalhes para acessar o conteúdo real.

O campo mediaFile inclui o baseUrl. Esse baseUrl é o que você vai usar para criar URLs para acessar o conteúdo do item de mídia em várias resoluções ou formatos.

URLs base

Os URLs de base nas APIs do Google Fotos oferecem acesso aos bytes brutos de itens de mídia, permitindo que seu app faça o download ou a exibição deles. Esses URLs são incluídos nas respostas ao listar álbuns (API Library) ou acessar itens de mídia (APIs Library e Picker). Lembre-se de que os URLs base exigem parâmetros adicionais para funcionar corretamente.

Para a API Picker:

Todos os objetos PickedMediaItem.mediaFile incluem um baseUrl.

Os URLs de base permanecem ativos por 60 minutos, mas podem expirar antes se o usuário revogar as permissões do app nas configurações da Conta do Google.

Para a API Library:

Os URLs de base permanecem ativos por 60 minutos.

Os vários URLs base são:

  • baseUrl: acessa diretamente a foto, a miniatura de um vídeo ou faz o download de bytes de vídeo.
  • coverPhotoBaseUrl: acessar diretamente a foto da capa do álbum.
  • profilePictureBaseUrl: acessa diretamente a foto do perfil do proprietário de um mediaItem.

URLs de base de imagens

Confira a lista de opções que podem ser usadas com os URLs de base de imagens:

Parâmetro
w, h

Descrição

Os parâmetros de largura, w e altura, h.

Para acessar um item de mídia de imagem, como uma foto ou uma miniatura de um vídeo, especifique as dimensões que você planeja mostrar no aplicativo para que a imagem possa ser dimensionada nessas dimensões, preservando a proporção. Para fazer isso, concatene o URL de base com as dimensões necessárias, conforme mostrado nos exemplos.

Exemplos:

base-url=wmax-width-hmax-height

Confira um exemplo de como mostrar um item de mídia com largura máxima de 2.048 px e altura máxima de 1.024 px:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

Descrição

O parâmetro c de corte.

Se você quiser cortar a imagem para as dimensões exatas de largura e altura especificadas, concatenar o URL de base com o parâmetro -c opcional e os parâmetros obrigatórios w e h.

O tamanho (em pixels) precisa estar no intervalo [1, 16383]. Se a largura ou a altura da imagem exceder o tamanho solicitado, ela será reduzida e cortada (mantendo a proporção).

Exemplos:

base-url=wmax-width-hmax-height-c

Neste exemplo, o aplicativo mostra um item de mídia com 256 px de largura e 256 px de altura, como uma miniatura:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

Descrição

O download, parâmetro d.

Se você quiser fazer o download da imagem mantendo todos os metadados do Exif, exceto os metadados de local, concatenar o URL base com o parâmetro d.

Exemplos:

base-url=d

Neste exemplo, o aplicativo faz o download de uma imagem com todos os metadados, exceto os de local:

https://lh3.googleusercontent.com/p/Az....XabC=d

URLs de base dos vídeos

Confira a lista de opções que você pode usar com os URLs de base de vídeo:

Parâmetro
dv

Descrição

Para acessar os bytes de um vídeo mediaItem, concatenar o baseUrl com o parâmetro dv de download de vídeo.

O parâmetro dv solicita uma versão transcodificada de alta qualidade do vídeo original. O parâmetro não é compatível com os parâmetros w e h.

Os URLs de base para downloads de vídeo podem levar alguns segundos para retornar bytes.

Antes de usar esse parâmetro, verifique se o campo mediaMetadata.status dos itens de mídia é READY. Caso contrário, se o item de mídia não tiver concluído o processamento, você poderá receber um erro.

Exemplos:

base-url=dv

O exemplo a seguir mostra como fazer o download dos bytes de um vídeo:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c e d

Descrição

Para acessar a miniatura do vídeo, use qualquer um dos parâmetros de URL de imagem base.

Por padrão, todas as miniaturas de vídeo incluem uma sobreposição de um botão de reprodução. Consulte o parâmetro -no para remover essa sobreposição.

Exemplos:

Consulte a tabela de URLs de base de imagens para conferir exemplos.
no

Descrição

A sobreposição de miniaturas a ser removida, parâmetro no.

Se você quiser recuperar a miniatura de um vídeo sem a sobreposição de um botão de reprodução, concatenar o URL base com o parâmetro no.

O parâmetro no precisa ser usado com pelo menos um dos parâmetros de URL de base da imagem.

Exemplos:

base-url=wmax-width-hmax-height-no

O exemplo a seguir mostra uma miniatura de vídeo com exatamente 1.280 px de largura por 720 px de altura e não inclui uma sobreposição de botão de reprodução:

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URLs base de fotos com movimento

As fotos com movimento contêm elementos de foto e vídeo. É possível usar parâmetros de URLs de base de imagem ou URLs de base de vídeo para solicitações de baseUrl de fotos em movimento.

Parâmetro
dv

Descrição

Para recuperar o elemento de vídeo de um item de mídia de foto com movimento, use o parâmetro dv como faria para fazer o download de URLs de base de vídeo.
w, h, c e d

Descrição

Para recuperar o elemento de foto de um item de mídia de foto em movimento, use o formato de URLs de base de imagens.

Próximas etapas

  • Aplicativo de exemplo:nosso aplicativo de exemplo inclui um exemplo de como listar e recuperar itens de mídia. Confira as funções checkMediaSourcesSet e fetch_media_item_list para mais informações.
  • Documentação de referência:consulte as documentações completas de referência sobre itens de mídia para informações detalhadas sobre todos os métodos, parâmetros de solicitação e resposta e códigos de erro disponíveis.