Les enrichissements permettent à votre application de contrôler la structure et la présentation des photos au sein d'un album dans Google Photos. Elles vous permettent de fournir à l'utilisateur plus de contexte par le biais d'annotations textuelles ou de lieux, et d'images d'ordre/groupe qui racontent une histoire.
Champ d'application des autorisations requis
Pour ajouter des informations enrichies, vous devez disposer d'au moins l'un des champs d'application suivants:
photoslibrary.appendonly
photoslibrary.library
photoslibrary.sharing
Pour chaque champ d'application, l'appel enrichAlbum
est limité aux albums créés par l'application.
Lorsque vous utilisez le champ d'application .sharing
, enrichAlbum
est limité aux cas où le développeur agit au nom du propriétaire de l'album partagé.
Types d'enrichissements
Google Photos propose trois types d'enrichissements dans les albums: texte, lieux et cartes.
Enrichissements de texte
Une chaîne de texte brut peut être insérée pour annoter l'album.
Enrichissements de lieux
Les informations de localisation enrichies sont un repère accompagné du nom du lieu qui peut être inséré pour annoter un lieu.
Enrichissements de cartes
Une carte enrichie est une carte dont le point de départ et la destination sont spécifiés et qui peut être insérée dans l'album.
Positions
Pour insérer des éléments multimédias et des éléments enrichis d'album, spécifiez la position de l'album. Une position est facultative pour les éléments multimédias, mais elle doit être spécifiée pour enrichir l'album.
Vous ne pouvez spécifier une position que lors de la création d'un élément multimédia ou de l'ajout d'éléments enrichis. Les éléments multimédias existants dans un album ne peuvent pas être réorganisés. Il est donc important de définir la position d'un élément lorsqu'il est ajouté.
Début de l'album
Un élément multimédia ou d'enrichissement peut être ajouté au début de l'album en tant que positionnement absolu.
Fin de l'album
Un élément multimédia ou d'enrichissement peut être ajouté à la fin de l'album pour un positionnement absolu.
Par rapport à l'élément multimédia
Un élément multimédia/d'enrichissement peut être ajouté par rapport à un élément multimédia en commençant après sa position dans l'album.
Par rapport à l'élément d'enrichissement
Un élément multimédia/d'enrichissement peut être ajouté par rapport à un élément d'enrichissement en commençant par sa position dans l'album.
Enrichissez l'album
Les éléments enrichissants sont ajoutés un par un et doivent être ajoutés à une position dans un album.
Pour enrichir un album, appelez albums.addEnrichment
.
Si la requête aboutit, elle renvoie la valeur id
de l'élément d'enrichissement, qui peut être utilisée pour positionner des éléments multimédias ou d'autres éléments d'enrichissement.
REST
Voici une requête POST:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment Content-type: application/json Authorization: Bearer oauth2-token request-body
Le corps de la requête comprend l'élément d'enrichissement et sa position:
{ "newEnrichmentItem": { enrichment-to-be-added }, "albumPosition": { position-of-enrichment }
Voici un exemple de réponse :
{ "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 }
Enrichissements acceptés
Enrichissements de texte
Les enrichissements de texte contiennent une seule chaîne de texte (1 000 caractères maximum), comme illustré dans l'exemple suivant:
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");
Enrichissements de lieux
Les extensions de lieu se composent d'un nom d'emplacement arbitraire ainsi que de la position de latitude et de longitude. Le locationName
est limité à 500 caractères.
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);
Enrichissements de cartes
Les enrichissements de cartes montrent deux lieux, chacun avec un nom, ainsi que la latitude et la longitude. Comme pour l'enrichissement des lieux, le locationName
dans l'origine et dans destination
est limité à 500 caractères.
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);
Positionnement accepté
Début de l'album
La position FIRST_IN_ALBUM
correspond au début de l'album. Les éléments situés ici sont d'abord présentés à l'utilisateur:
REST
{ "position": "FIRST_IN_ALBUM", }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();
PHP
$albumPosition = new AlbumPosition(); $albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);
Fin de l'album
La position LAST_IN_ALBUM
correspond à la fin de l'album. Les éléments situés ici sont présentés à l'utilisateur en dernier.
REST
{ "position": "LAST_IN_ALBUM", }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();
PHP
$albumPosition = new AlbumPosition(); $albumPosition->setPosition(PositionType::LAST_IN_ALBUM);
Par rapport à l'élément multimédia
Spécifier la position relativeMediaItem
fait référence à une position par rapport à un élément multimédia. Les éléments sont ajoutés après l'élément multimédia spécifié.
REST
{ "position": "after-media-item", "relativeMediaItemId": "media-item-id" }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
Par rapport à l'élément d'enrichissement
Spécifier un relativeEnrichmentItemId
fait référence à une position par rapport à un élément d'enrichissement. Les éléments sont ajoutés après l'élément d'enrichissement spécifié.
REST
{ "position": "after-enrichment-item", "relativeEnrichmentItemId": "enrichment-item-id" }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);
Modifier les enrichissements
Il n'existe actuellement aucun moyen de modifier les éléments enrichis. Toutefois, une fois qu'un enrichissement a été créé et ajouté à un album, l'utilisateur peut le modifier via l'application Google Photos.