Ajouter des informations enrichies

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.

Capture d'écran de texte enrichi dans Google Photos

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.

Capture d'écran d'une fonctionnalité enrichie d'un lieu dans Google Photos

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.

Capture d'écran d'une zone d'enrichissement de carte affichée dans Google Photos

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.