Depois de fazer chamadas para listar o conteúdo de uma biblioteca ou álbum de fotos, em vez de armazenar os itens de mídia retornados, o aplicativo precisa armazenar os IDs dos itens de mídia. Isso ocorre porque o conteúdo dos itens de mídia pode mudar e, após um determinado período, os URLs incluídos na resposta expiram. O ID do item de mídia identifica exclusivamente um item de mídia, como uma foto ou um vídeo na biblioteca de um usuário.
Escopos de autorização necessários
O acesso a itens de mídia criados pelo app requer o
escopo photoslibrary.readonly.appcreateddata. Para mais informações sobre escopos, consulte Escopos de autorização.
Itens de mídia
Um mediaItem
é uma representação de mídia, como uma foto ou um vídeo que foi enviado para
a biblioteca do Google Fotos. Ele é um objeto de nível superior, e as propriedades dele podem
diferir com base no tipo de mídia.
A tabela a seguir lista as propriedades mediaItem:
| Propriedades | |
|---|---|
id |
Um ID permanente e estável usado para identificar o objeto. |
description |
Descrição do item de mídia no Google Fotos. |
baseUrl |
Usado para acessar os bytes brutos. Para mais informações, consulte URLs base. |
productUrl |
Um link para a imagem no Google Fotos. Esse link não pode ser aberto pelo desenvolvedor, apenas pelo usuário. Os URLs apontam para um item de mídia na biblioteca. Se o URL foi extraído de uma pesquisa de álbum, ele aponta para o item dentro do álbum. |
mimeType |
O tipo do item de mídia para ajudar a identificar facilmente o tipo de mídia
(por exemplo: image/jpg). |
filename |
O nome do arquivo do item de mídia mostrado ao usuário no app Google Fotos (na seção de informações do item). |
mediaMetadata |
Varia de acordo com o tipo de mídia, como photo
ou video.
Para reduzir o payload, é possível usar máscaras de campo.
|
Acessar um item de mídia
Para recuperar um item de mídia, chame
mediaItems.get usando o
mediaItemId. A solicitação retorna um único item de mídia.
O mediaItem contém propriedades, como o ID, a descrição e o URL. As
informações adicionais em photo ou video são baseadas nos metadados do
arquivo. Nem todas as propriedades podem estar presentes.
Se o item de mídia for um vídeo, o arquivo de vídeo terá que ser processado primeiro. O
mediaItem contém um campo status dentro de mediaMetadata, que descreve o
estado de processamento do arquivo de vídeo. Um arquivo recém-enviado retorna o
videoProcessingStatus
com o valor PROCESSING primeiro, antes de ser READY para uso. O baseUrl
de um item de mídia de vídeo não fica disponível até que o vídeo seja processado.
REST
Aqui está uma solicitação GET:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
A resposta para um item de mídia de foto é assim. A propriedade de foto contém metadados para itens de foto.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"photo": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"focalLength": "focal-length-of-the-camera-lens",
"apertureFNumber": "aperture-f-number-of-the-camera-lens",
"isoEquivalent": "iso-of-the-camera",
"exposureTime": "exposure-time-of-the-camera-aperture"
}
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
A resposta para um item de mídia de vídeo é assim: A propriedade de vídeo contém metadados para itens de vídeo.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"video": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"fps": "frame-rate-of-the-video",
"status": "READY"
},
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
Acessar vários itens de mídia
Para recuperar vários itens de mídia pelos identificadores, chame
mediaItems.batchGet
usando os mediaItemIds.
A solicitação retorna uma lista de
MediaItemResults
na ordem dos identificadores de itens de mídia fornecidos na solicitação. Cada resultado
contém um MediaItem
ou um Status se houver um erro.
O número máximo de itens de mídia que você pode solicitar em uma chamada é 50. A lista de itens de mídia não pode estar vazia e não pode conter identificadores duplicados.
REST
Esta é uma solicitação GET que mostra o acesso bem-sucedido e com falha de
itens de mídia. Especifique cada identificador de item de mídia como um novo
parâmetro de consulta mediaItemIds como parte da solicitação:
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id Content-type: application/json Authorization: Bearer oauth2-token
A solicitação GET retorna a seguinte resposta:
{
"mediaItemResults": [
{
"mediaItem": {
"id": "media-item-id",
...
}
},
{
"mediaItem": {
"id": "another-media-item-id",
...
}
},
{
"status": {
"code": 3,
"message": "Invalid media item ID."
}
}
]
}
URLs base
Os URLs de base nas APIs do Google Fotos dão acesso aos bytes brutos de itens de mídia, permitindo que o app faça o download deles ou os exiba. 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 ummediaItem.
URLs de base de imagem
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, 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 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 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 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 com 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 download, parâmetro Se você quiser fazer o download da imagem que retém todos os metadados Exif, exceto os metadados de local, concatene o URL de base com o parâmetro 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 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ídeos podem levar 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 da 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 base de imagem para exemplos. |
no |
Descrição A sobreposição de miniaturas a ser removida, parâmetro 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 sem uma sobreposição de botão de reprodução: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
URLs de base das fotos em 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 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 |
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. |