Gli arricchimenti consentono all'applicazione di controllare la struttura e la presentazione delle foto all'interno di un album in Google Foto. Ti consentono di presentare all'utente un contesto aggiuntivo tramite annotazioni di testo o di località e immagini di ordine/gruppo che raccontano una storia insieme.
Ambito dell'autorizzazione obbligatorio
Per aggiungere arricchimenti, è richiesto almeno uno dei seguenti ambiti:
photoslibrary.appendonly
photoslibrary.library
photoslibrary.sharing
Per ogni ambito, la chiamata enrichAlbum
è limitata solo agli album creati
dall'app.
Quando utilizzi l'ambito .sharing
, enrichAlbum
è limitato ai casi
in cui lo sviluppatore agisce per conto del proprietario dell'album condiviso.
Tipi di arricchimento
Google Foto supporta tre tipi di arricchimento per gli album: testo, località e mappe.
Arricchimenti del testo
Un arricchimento di testo è una stringa di testo normale che può essere inserita per annotare l'album.
Arricchimenti della località
Un arricchimento di località è un indicatore e il nome del luogo che possono essere inseriti per annotare una località.
Arricchimenti della mappa
Un arricchimento mappa è una mappa con un'origine e una destinazione specificate che possono essere inserite nell'album.
Posizioni
Per inserire elementi multimediali e arricchimenti dell'album, specifica la posizione dell'album. La posizione è facoltativa per gli elementi multimediali, ma deve essere specificata per l'arricchimento dell'album.
Una posizione può essere specificata solo durante la creazione di un elemento multimediale o l'aggiunta di arricchimenti. Gli elementi multimediali esistenti in un album non possono essere riorganizzati, pertanto è importante impostare la posizione di un elemento quando viene aggiunto.
Inizio dell'album
Un elemento multimediale/di arricchimento può essere aggiunto all'inizio dell'album come posizionamento assoluto.
Fine dell'album
Un elemento multimediale/di arricchimento può essere aggiunto alla fine dell'album come posizionamento assoluto.
Rispetto all'elemento multimediale
Puoi aggiungere un elemento multimediale/di arricchimento relativo a un elemento multimediale che inizia dopo la sua posizione nell'album.
Rispetto all'elemento di arricchimento
Un elemento multimediale/di arricchimento può essere aggiunto in base a un elemento di arricchimento che inizia dopo la sua posizione nell'album.
Aggiunta di arricchimenti all'album
Gli Arricchimenti vengono aggiunti uno alla volta e devono essere aggiunti a una posizione di un album.
Per aggiungere arricchimenti a un album, chiama
albums.addEnrichment
.
Se la richiesta ha esito positivo, restituisce il valore id
dell'elemento di arricchimento, che può essere utilizzato per posizionare elementi multimediali o altri arricchimenti.
REST
Ecco una richiesta POST:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment Content-type: application/json Authorization: Bearer oauth2-token request-body
Il corpo della richiesta è composto dall'elemento di arricchimento e dalla sua posizione:
{ "newEnrichmentItem": { enrichment-to-be-added }, "albumPosition": { position-of-enrichment }
Ecco un esempio di risposta:
{ "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 }
Arricchimenti supportati
Arricchimenti del testo
Gli arricchimenti di testo contengono una singola stringa di testo (non più di 1000 caratteri), come mostrato nell'esempio seguente:
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");
Arricchimenti della località
Gli arricchimenti relativi alla località consistono in un nome di località arbitrario e nella posizione di latitudine e longitudine. Il campo locationName
è limitato a 500 caratteri.
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);
Arricchimenti della mappa
Gli arricchimenti della mappa mostrano due località, ciascuna costituita da un nome e da latitudine e longitudine. Analogamente all'arricchimento della località, il valore locationName
all'interno dell'origine e di destination
è limitato a 500 caratteri.
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);
Posizionamento supportato
Inizio dell'album
La posizione FIRST_IN_ALBUM
si riferisce all'inizio dell'album. Gli elementi situati
qui vengono mostrati per primi all'utente:
REST
{ "position": "FIRST_IN_ALBUM", }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();
PHP
$albumPosition = new AlbumPosition(); $albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);
Fine dell'album
La posizione LAST_IN_ALBUM
si riferisce alla fine dell'album. Gli elementi situati qui
vengono mostrati all'utente per ultimi.
REST
{ "position": "LAST_IN_ALBUM", }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();
PHP
$albumPosition = new AlbumPosition(); $albumPosition->setPosition(PositionType::LAST_IN_ALBUM);
Rispetto all'elemento multimediale
Se specifichi la posizione relativeMediaItem
, fai riferimento a una posizione relativa a un
elemento multimediale. Gli elementi vengono aggiunti dopo l'elemento multimediale specificato.
REST
{ "position": "after-media-item", "relativeMediaItemId": "media-item-id" }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
Rispetto all'elemento di arricchimento
Se specifichi un valore relativeEnrichmentItemId
, fai riferimento a una posizione relativa a un
elemento di arricchimento. Gli elementi vengono aggiunti dopo l'elemento di arricchimento specificato.
REST
{ "position": "after-enrichment-item", "relativeEnrichmentItemId": "enrichment-item-id" }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);
Modificare gli arricchimenti
Al momento, non è possibile modificare gli arricchimenti. Tuttavia, una volta creato e aggiunto un arricchimento a un album, l'utente può modificarlo tramite l'app Google Foto.