Com os aprimoramentos, seu app controla a estrutura e a apresentação das fotos em um álbum no Google Fotos. Com elas, é possível apresentar ao usuário mais contexto usando anotações de texto ou local e imagens de ordem/agrupamento que contam uma história em conjunto.
Escopo de autorização obrigatório
Para adicionar enriquecimentos, pelo menos um dos seguintes escopos é obrigatório:
photoslibrary.appendonly
photoslibrary.library
photoslibrary.sharing
Para cada escopo, a chamada enrichAlbum
é restrita apenas aos álbuns criados
pelo app.
Ao usar o escopo .sharing
, enrichAlbum
é restrito a circunstâncias
em que o desenvolvedor está agindo em nome do proprietário do álbum compartilhado.
Tipos de enriquecimento
O Google Fotos é compatível com três tipos de aprimoramentos em álbuns: texto, locais e mapas.
Aprimoramentos de texto
Um enriquecimento de texto é uma string de texto simples que pode ser inserida para anotar o álbum.
Aprimoramentos de local
Um enriquecimento de local é um marcador e o nome do lugar que pode ser inserido para anotar um local.
Aprimoramentos de mapas
Um aprimoramento de mapa é aquele com uma origem e um destino especificados que podem ser inseridos no álbum.
Posições
Para inserir itens de mídia e enriquecimentos de álbuns, especifique a posição do álbum. Uma posição é opcional para itens de mídia, mas precisa ser especificada para enriquecimento do álbum.
Uma posição só pode ser especificada ao criar um item de mídia ou adicionar enriquecimentos. Os itens de mídia existentes em um álbum não podem ser reorganizados, por isso é importante definir a posição de um item quando ele estiver sendo adicionado.
Início do álbum
Um item de mídia/enriquecimento pode ser adicionado ao início do álbum como posicionamento absoluto.
Fim do álbum
Um item de mídia/enriquecimento pode ser adicionado ao final do álbum como posicionamento absoluto.
Relativo ao item de mídia
Um item de mídia/enriquecimento pode ser adicionado em relação a um item de mídia começando após a posição dele no álbum.
Relativo ao item de enriquecimento
Um item de mídia/enriquecimento pode ser adicionado em relação a um item de enriquecimento começando após a posição no álbum.
Adicionar melhorias ao álbum
Os aprimoramentos são adicionados um de cada vez e precisam ser incluídos em uma posição em um álbum.
Para adicionar melhorias a um álbum, chame
albums.addEnrichment
.
Se a solicitação for bem-sucedida, ela retornará o id
do item de enriquecimento, que
pode ser usado para posicionar itens de mídia ou outros aprimoramentos.
REST
Esta é uma solicitação POST:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment Content-type: application/json Authorization: Bearer oauth2-token request-body
O corpo da solicitação consiste no item de enriquecimento e na posição dele:
{ "newEnrichmentItem": { enrichment-to-be-added }, "albumPosition": { position-of-enrichment }
Veja um exemplo de resposta:
{ "enrichmentItem": { "id": "enrichment-item-id", } }
Java
try { // Create the enrichment using the NewEnrichmentItemFactory helper NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createTextEnrichment(""); // Set the position of the enrichment within the album AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum(); // To add an enrichment, specify the album, the enrichment item, // and the position in the album where the enrichment is to be added AddEnrichmentToAlbumResponse response = photosLibraryClient .addEnrichmentToAlbum(albumId, newEnrichmentItem, albumPosition); // The response contains an EnrichmentItem // whose ID can be used to position media items or other enrichments EnrichmentItem enrichmentItem = response.getEnrichmentItem(); String itemId = enrichmentItem.getId(); } catch (ApiException e) { // Handle error }
PHP
// Create the enrichment item using the PhotosLibraryResourceFactory helper $newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText(""); // ... // Set the position of the enrichment within the album $position = new AlbumPosition(); // ... try { // To add an enrichment, specify the album, the enrichment item, // and the position in the album where the enrichment is to be added $response = $photosLibraryClient->addEnrichmentToAlbum($albumId, $newEnrichmentItem, $position); // The response contains an EnrichmentItem // whose ID can be used to position media items or other enrichments $enrichmentItem = $response->getEnrichmentItem(); $itemId = $enrichmentItem->getId(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Aprimoramentos com suporte
Aprimoramentos de texto
Os enriquecimentos de texto contêm uma única string de texto (no máximo 1.000 caracteres), conforme mostrado neste exemplo:
REST
{ "text": "Text to be shown" }
Java
// Use the NewEnrichmentItemFactory helper to create a text enrichment item NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createTextEnrichment("text to be shown");
PHP
$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("text to be shown");
Aprimoramentos de local
As melhorias de local consistem em um nome de local arbitrário e a posição de latitude e longitude. O locationName
é limitado a 500 caracteres.
REST
{ "location": { "locationName": "Australia", "latlng": { "latitude": "-21.197", "longitude": "95.821" } } }
Java
// Use the NewEnrichmentItemFactory helper to create a location enrichment // with the name, latitude, and longitude of the location NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createLocationEnrichment("Australia", -21.197, 95.821);
PHP
// Create a new location object and set the name, latitude, and longitude of the location $newLocation = new Location(); $newLocation->setLocationName("Australia"); $newLocation->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821)); $newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithLocation($newLocation);
Aprimoramentos de mapas
Os aprimoramentos do mapa mostram dois locais, cada um consistindo em um nome e latitude e longitude. Assim como o aprimoramento de local, locationName
na origem e destination
é limitado a 500 caracteres.
REST
{ "origin": { "locationName": "Australia", "latlng": { "latitude": "-21.197", "longitude": "95.821" } }, "destination": { "locationName": "San Francisco", "latlng": { "latitude": "37.757", "longitude": "122.507" } } }
Java
// Use the NewEnrichmentItemFactory helper to create a map enrichment item for // an origin and a destination location NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createMapEnrichment( "Australia", -21.197, 95.821, // origin "San Francisco", 37.757, 122.507 // destination );
PHP
// Create two new location objects to create a map enrichment item // for an origin and a destination location $locationAustralia = new Location(); $locationAustralia->setLocationName("Australia"); $locationAustralia->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821)); $locationSanFrancisco = new Location(); $locationSanFrancisco->setLocationName("San Francisco"); $locationSanFrancisco->setLatlng((new LatLng())->setLatitude(37.757)->setLongitude(122.507)); $newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithMap($locationAustralia, $locationSanFrancisco);
Posicionamento compatível
Início do álbum
A posição FIRST_IN_ALBUM
refere-se ao início do álbum. Os itens localizados
aqui são mostrados primeiro para o usuário:
REST
{ "position": "FIRST_IN_ALBUM", }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();
PHP
$albumPosition = new AlbumPosition(); $albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);
Fim do álbum
A posição LAST_IN_ALBUM
refere-se ao fim do álbum. Os itens localizados aqui
são mostrados ao usuário por último.
REST
{ "position": "LAST_IN_ALBUM", }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();
PHP
$albumPosition = new AlbumPosition(); $albumPosition->setPosition(PositionType::LAST_IN_ALBUM);
Relativo ao item de mídia
A especificação da posição relativeMediaItem
refere-se a uma posição relativa a um
item de mídia. Os itens são adicionados após o item de mídia especificado.
REST
{ "position": "after-media-item", "relativeMediaItemId": "media-item-id" }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
Relativo ao item de enriquecimento
Especificar um relativeEnrichmentItemId
refere-se a uma posição relativa a um
item de enriquecimento. Os itens são adicionados após o item de enriquecimento especificado.
REST
{ "position": "after-enrichment-item", "relativeEnrichmentItemId": "enrichment-item-id" }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);
Como modificar enriquecimentos
Atualmente, não há como modificar os enriquecimentos. No entanto, depois que uma melhoria é criada e adicionada a um álbum, o usuário pode modificá-la pelo app Google Fotos.