Depois de fazer chamadas para listar o conteúdo de uma biblioteca de fotos ou um álbum, em vez de armazenar os itens de mídia retornados, o aplicativo deve armazenar os IDs dos itens de mídia. Isso ocorre porque o conteúdo dos itens de mídia pode mudar e, depois de um determinado tempo, os URLs incluídos na resposta expiram. A ID de item de mídia identifica exclusivamente um item de mídia, como uma foto ou um vídeo na biblioteca de um usuário.
Observe que seu aplicativo não deve armazenar em cache a foto ou o vídeo de um usuário por muito tempo específicos, mas, dependendo do caso de uso, você pode armazenar ou armazenar em cache o ID do item de mídia longo como necessários. Observe também que o acesso a ferramentas de dados são regidos pelos requisitos de privacidade obrigações de privacidade de dados.
Escopos de autorização necessários
Para acessar itens de mídia, o app precisa solicitar pelo menos um dos seguintes escopos de autorização. O acesso aos itens de mídia retornados na resposta depende dos escopos solicitaram.
photoslibrary.readonly
permite o acesso a todos os itens de mídia da conta do usuário bibliotecaphotoslibrary.readonly.appcreateddata
permite o acesso somente a itens de mídia que foram criadas pelo app
Itens de mídia
Um
mediaItem
é uma representação de mídia, como uma foto ou um vídeo, que foi enviado ao
a biblioteca do Google Fotos. É um objeto de nível superior e suas propriedades podem
diferem com base no tipo de mídia.
A tabela abaixo lista as propriedades de mediaItem
:
Propriedades | |
---|---|
id |
Um ID permanente e estável usado para identificar o objeto. |
description |
Descrição do item de mídia exibido na parte interna 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. Este link não pode ser aberto pelo desenvolvedor, apenas pelo usuário. Os URLs apontam para um item de mídia da biblioteca. Se o URL foi recuperado de uma pesquisa de álbum, ele aponta para o item no á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 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.
|
contributorInfo |
Esse campo só é preenchido se o item de mídia está em um álbum compartilhado.
criado por este app, e o usuário deu a permissão
escopo Contém informações sobre o colaborador que adicionou a mídia do item de linha. Para mais detalhes, consulte Compartilhar mídia. |
Receber 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 ID, descrição e URL. A
informações adicionais em photo
ou video
são baseadas nos metadados em
o arquivo. É possível que nem todas as propriedades estejam presentes. ContributorInfo
contém metadados.
para itens que fazem parte de um álbum compartilhado. Esse campo só é incluído quando
listar o conteúdo de um
álbum compartilhado em que o usuário concedeu a permissão photoslibrary.sharing
escopo da autorização.
Se o item de mídia for um vídeo, o arquivo de vídeo terá que ser processado primeiro. A
mediaItem
contém um campo status
dentro de mediaMetadata
que descreve a
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 em vídeo não estará disponível até que o vídeo tenha sido 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 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. O vídeo contém metadados de 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" } }
Java
A propriedade foto contém metadados para itens de foto.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasPhoto()) { // This media item is a photo and has additional photo metadata Photo photoMetadata = metadata.getPhoto(); String cameraMake = photoMetadata.getCameraMake(); String cameraModel = photoMetadata.getCameraModel(); float aperture = photoMetadata.getApertureFNumber(); int isoEquivalent = photoMetadata.getIsoEquivalent(); // ... } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
A propriedade de vídeo contém metadados para itens de vídeo.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasVideo()) { // This media item is a video and has additional video metadata Video videoMetadata = metadata.getVideo(); VideoProcessingStatus status = videoMetadata.getStatus(); if (status.equals(VideoProcessingStatus.READY)) { // This video media item has been processed String cameraMake = videoMetadata.getCameraMake(); String cameraModel = videoMetadata.getCameraModel(); double fps = videoMetadata.getFps(); // ... } } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
PHP
A propriedade foto contém metadados para itens de foto.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $photoMetadata = $metadata->getPhoto(); if (!is_null($photoMetadata)) { // This media item is a photo and has additional photo metadata $cameraMake = $photoMetadata->getCameraMake(); $cameraModel = $photoMetadata->getCameraModel(); $aperture = $photoMetadata->getApertureFNumber(); $isoEquivalent = $photoMetadata->getIsoEquivalent(); // ... } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
A propriedade de vídeo contém metadados para itens de vídeo.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $videoMetadata = $metadata->getVideo(); if (!is_null($videoMetadata)) { // This media item is a video and has additional video metadata if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) { // This video media item has been processed $cameraMake = $videoMetadata->getCameraMake(); $cameraModel = $videoMetadata->getCameraModel(); $fps = $videoMetadata->getFps(); // ... } } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Receber vários itens de mídia
Para recuperar vários itens de mídia pelos identificadores, chame
mediaItems.batchGet
usando as mediaItemId
s.
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 os itens de mídia não podem conter identificadores duplicados nem podem ficar em branco.
REST
Aqui está uma solicitação GET que mostra o acesso bem-sucedido e malsucedido de
itens de mídia. Especifique cada identificador de item de mídia como um novo
o 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." } } ] }
Java
try { // List of media item IDs to retrieve List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"); // Get a list of media items using their IDs BatchGetMediaItemsResponse response = photosLibraryClient .batchGetMediaItems(mediaItemIds); // Loop over each result for (MediaItemResult result : response.getMediaItemResultsList()) { // Each MediaItemresult contains a status and a media item if (result.hasMediaItem()) { // The media item was successfully retrieved, get some properties MediaItem item = result.getMediaItem(); String id = item.getId(); // ... } else { // If the media item is not set, an error occurred and the item could not be loaded // Check the status and handle the error Status status = result.getStatus(); // ... } } } catch (ApiException e) { // Handle error }
PHP
try { // List of media item IDs to retrieve $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"]; // Get a list of media items using their IDs $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds); // Loop over each result foreach ($response->getMediaItemResults() as $itemResult) { // Each MediaItemresult contains a status and a media item $mediaItem = $itemResult->getMediaItem(); if(!is_null($mediaItem)){ // The media item was successfully retrieved, get some properties $id = $mediaItem->getId(); // ... } else { // If the media item is null, an error occurred and the item could not be loaded } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
URLs base
Os URLs de base na API Google Photos Library permitem que você acesse os bytes da mídia itens. Usando os diversos URLs base, o app pode fazer o download dos itens de mídia ou exibir os itens de mídia dentro do app. Os URLs base são strings incluído na resposta quando você lista álbuns ou acessa itens de mídia. São são válidos por 60 minutos e exigem parâmetros adicionais, já que não podem ser usados como o endereço IP interno.
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 de perfil do proprietário de ummediaItem
.
URLs de base de imagem
Esta é a lista de opções que podem ser usadas com os URLs de base de imagem:
Parâmetro | |
---|---|
w , h |
Descrição A largura, Para acessar um item de mídia de imagem, como uma foto ou uma miniatura, um vídeo, é necessário especificar as dimensões que você planeja exibir em do aplicativo (para que a imagem possa ser dimensionada e manter a proporção). Para isso, concatenar o URL base com as dimensões necessárias, como mostrado em os exemplos. Exemplos: base-url=wmax-width-hmax-height Este é um exemplo para exibir um item de mídia com largura menor que 2.048 px e não mais que 1.024 px: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Descrição O corte, parâmetro Se você quiser cortar a imagem na largura e altura exatas
especificadas, concatene o URL base com o
parâmetro O tamanho (em pixels) deve estar no intervalo [1, 16383]. Se a largura ou a altura da imagem, exceder o tamanho solicitado, o é reduzida e cortada (mantendo a proporção). Exemplos: base-url=wmax-width-hmax-height-c Neste exemplo, o aplicativo exibe um item de mídia que é exatamente 256 px de largura por 256 px de altura, como 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 exceto os metadados de local: https://lh3.googleusercontent.com/p/Az....XabC=d |
URLs de base de vídeo
Esta é 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 alta qualidade, versão transcodificada do vídeo original. O parâmetro não é compatível com w e h parâmetros. Os URLs de base para downloads de vídeo podem levar alguns segundos para retornam bytes. Os downloads de vídeo usam a codificação H.264 por padrão. Se a codificação H.264 falhar, o VP9 será usado. Antes de usar esse parâmetro, verifique se o valor
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 um dos parâmetros de URL base da imagem. Por padrão, todas as miniaturas de vídeo incluem uma sobreposição de um vídeo . Consulte o parâmetro -no para remover essa sobreposição. Exemplos: Consulte a tabela de URLs base de imagem. 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 sinal no . O parâmetro no precisa ser usado com pelo menos um dos as parâmetros de URL de base da imagem. Exemplos: base-url=wmax-width-hmax-height-no O exemplo a seguir exibe uma miniatura de vídeo com exatamente 1280 px de largura por 720 px de altura e não inclui uma sobreposição do 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 de foto com movimento baseUrl
.
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 com movimento, use o formato dos URLs de base de imagem. |