Depois que um usuário configurar o dispositivo ambiente e selecionar fontes de mídia no Google Fotos, seu aplicativo poderá listar e recuperar esses itens de mídia para exibição.
Antes de começar
- Verifique a configuração do dispositivo:confira se você criou e configurou um dispositivo para o usuário.
- Entenda o fluxo da API Ambient:revise 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 selecionar as fotos que quer compartilhar com seu aplicativo no app Google Fotos. Seu aplicativo 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 selecionar as fontes de mídia, este campo vai mudar para true.
A resposta AmbientDevice inclui um pollingConfig com um pollInterval
que você deve usar como diretriz para sua frequência de pesquisa.
Listar itens de mídia
Quando mediaSourcesSet for true em um dispositivo, comece a buscar os itens de mídia selecionados pelo usuário.
Use o endpoint
mediaItems.list:faça uma solicitação GET parahttps://photosambient.googleapis.com/v1/mediaItems, fornecendo odeviceIdno caminho.Processar paginação (se necessário): a resposta pode ser paginada. Use o parâmetro
pageSizepara especificar o número máximo de itens a serem retornados e opageTokende uma resposta anterior para recuperar as páginas subsequentes de resultados.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 e acessar o conteúdo do item de mídia em várias
resoluções ou formatos.
URLs base
Os URLs de base nas APIs Google Fotos fornecem acesso aos bytes brutos de itens de mídia, permitindo que seu app faça o download ou mostre esses itens. 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 de 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 de base são:
baseUrl: acesso direto a fotos, miniaturas de vídeos ou download de bytes de vídeo.coverPhotoBaseUrl: acessa diretamente a foto da capa do álbum.profilePictureBaseUrl: acesse diretamente a foto de perfil do proprietário de ummediaItem.
URLs de base de imagens
Confira a lista de opções que você pode usar com os URLs de base de imagem:
| Parâmetro | |
|---|---|
w, h |
Descrição Os parâmetros de largura, Para acessar um item de mídia de imagem, como uma foto ou uma miniatura de vídeo, especifique as dimensões que você planeja mostrar no aplicativo. Assim, a imagem pode ser dimensionada para essas 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 Este é um exemplo para 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 de corte, Se você quiser cortar a imagem exatamente nas dimensões de largura e altura especificadas, concatene o URL base com o parâmetro opcional 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 que tem exatamente 256 px de largura por 256 px de altura, como uma miniatura: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Descrição O parâmetro de download, Se quiser baixar a imagem mantendo todos os metadados Exif, exceto os de local, concatene o URL base com o parâmetro Exemplos: base-url=d Neste exemplo, o aplicativo baixa uma imagem com todos os metadados, exceto os de local: https://lh3.googleusercontent.com/p/Az....XabC=d |
URLs de base de vídeo
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 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 até alguns segundos para retornar bytes. Antes de usar esse parâmetro, verifique se o campo 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 base de imagem. 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 ver exemplos. |
no |
Descrição O parâmetro Se você quiser recuperar a miniatura de um vídeo sem a sobreposição de um botão de reprodução, concatene o URL base com o parâmetro no. O parâmetro no precisa ser usado com pelo menos um dos parâmetros de URL base da imagem. Exemplos: base-url=wmax-width-hmax-height-no O exemplo a seguir mostra uma miniatura de vídeo com exatamente 1280 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 base de imagens ou URLs base de vídeos para solicitações de baseUrl fotos dinâmicas.
| Parâmetro | |
|---|---|
dv |
Descrição Para recuperar o elemento de vídeo de um item de mídia de foto em movimento, use
o parâmetro |
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 para URLs de base de imagem. |
Política e filtragem de conteúdo
O Google Fotos aplica a filtragem de conteúdo padrão por padrão para imagens e vídeos exibidos em um dispositivo compartilhado, como uma TV ou um display digital. Esse filtro foi criado para otimizar a experiência de visualização, excluindo conteúdo como:
- Imagens funcionais (por exemplo, capturas de tela, documentos, recibos).
- Imagens que podem ser renderizadas de forma inadequada em uma tela grande (por exemplo, resolução muito baixa, desfoque, granulação excessiva).
- Conteúdo identificado como altamente pessoal ou sensível, que pode não ser destinado à exibição geral em um ambiente compartilhado.
Toda a filtragem de conteúdo é automatizada. Para dar aos usuários mais controle sobre o conteúdo exibido, permita que eles selecionem e atualizem manualmente as fontes de mídia usadas para a tela ambiente.
Próximas etapas
- Aplicativo de exemplo:nosso aplicativo de exemplo
inclui um exemplo de listagem e recuperação de itens de mídia. Confira as funções
checkMediaSourcesSetefetch_media_item_listpara mais informações. - Documentação de referência:consulte os documentos de referência abrangentes sobre itens de mídia para informações detalhadas sobre todos os métodos disponíveis, parâmetros de solicitação e resposta e códigos de erro.