Depois de fazer chamadas para listar o conteúdo de uma biblioteca de fotos ou álbum, 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 dentro da biblioteca de um usuário.
Seu aplicativo não pode armazenar em cache a foto ou o vídeo de um usuário por longos períodos. Porém, dependendo do seu caso de uso, você pode armazenar ou armazenar em cache o ID do item de mídia pelo tempo necessário. Também é importante lembrar que o acesso aos dados do usuário é regido por obrigações de privacidade.
Escopos de autorização obrigatórios
Para acessar itens de mídia, seu 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 solicitados.
photoslibrary.readonlypermite acesso a todos os itens de mídia na biblioteca do usuário.photoslibrary.readonly.appcreateddatapermite acesso apenas a itens de mídia que foram criados pelo app
Itens de mídia
Uma
mediaItem
é uma representação de mídia, como uma foto ou um vídeo que foi enviado para a
biblioteca do Google Fotos. É um objeto de nível superior, e as propriedades dele podem
divergir de acordo com o 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 visto 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. O desenvolvedor não pode abrir esse link, apenas o usuário. Os URLs direcionam para um item de mídia na biblioteca. Se o URL foi recuperado de uma pesquisa de álbum, ele vai apontar para o item dentro do álbum. |
mimeType |
O tipo de 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.
|
contributorInfo |
Esse campo só será preenchido se o item de mídia estiver em um álbum compartilhado
criado por esse app e o usuário tiver concedido o
escopo Contém informações sobre o colaborador que adicionou esse item de mídia. Veja mais detalhes em Compartilhar mídia. |
Receber um item de mídia
Para extrair 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. As
informações adicionais em photo ou video são baseadas nos metadados
do arquivo. Nem todas as propriedades podem estar presentes. ContributorInfo contém metadados
para itens que fazem parte de um álbum compartilhado. Esse campo só é incluído ao
listar o conteúdo de um
álbum compartilhado em que o usuário concedeu o
escopo de autorização photoslibrary.sharing.
Se o item de mídia for um vídeo, o arquivo desse vídeo precisará ser processado primeiro. 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 a
videoProcessingStatus
com o valor PROCESSING 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
Esta é 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 tem esta aparência. A propriedade "photo" 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 em vídeo tem esta aparência. A propriedade "video" 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"
}
}
Java
A propriedade da 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 da 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 extrair 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 Status se houver um erro.
O número máximo de itens de mídia que podem ser solicitados em uma chamada é 50. A lista de itens de mídia não pode conter identificadores duplicados nem estar vazia.
REST
Esta é uma solicitação GET que mostra acessos bem-sucedidos e mal-sucedidos aos
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."
}
}
]
}
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 base na API Google Photos Library permitem que você acesse os bytes dos itens de mídia. Usando os vários URLs de base, seu app pode fazer o download dos itens de mídia ou mostrá-los no app. Os URLs de base são strings incluídas na resposta quando você lista álbuns ou acessa itens de mídia. Eles são válidos por 60 minutos e exigem parâmetros adicionais, já que não podem ser usados no estado em que se encontram.
Os vários URLs de base são:
baseUrl: acessa diretamente a foto, a miniatura de um vídeo ou os bytes do vídeo de download.coverPhotoBaseUrl: acessar diretamente a foto da capa do álbum.profilePictureBaseUrl: acessar diretamente a foto do perfil do proprietário de umamediaItem.
URLs de base de imagem
Veja 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 um 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 Veja um exemplo de exibição de um item de mídia com no máximo 2.048 px e no máximo 1.024 px: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Descrição O parâmetro Se você quiser cortar a imagem de acordo com as dimensões de largura e altura exatas especificadas, concatene o URL de base com o parâmetro opcional O tamanho (em pixels) deve estar no intervalo [1, 16383]. Se a largura ou a altura da imagem excederem o tamanho solicitado, a imagem será 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 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 você quiser fazer o download da imagem que retém todos os metadados EXIF, exceto os 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 metadados de local: https://lh3.googleusercontent.com/p/Az....XabC=d |
URLs de base de vídeo
Veja 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 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. Pode levar alguns segundos para que os URLs de base para downloads de vídeo retornem 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 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 miniatura removida, 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 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 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 imagens ou de URLs de vídeo de base para solicitações baseUrl de fotos com 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 com movimento, use o formato para URLs base de imagem. |