Ajouter des enrichissements

Les enrichissements permettent à votre application de contrôler la structure et la présentation des photos dans un album Google Photos. Elles vous permettent de présenter à l'utilisateur du contexte supplémentaire via des annotations textuelles ou de localisation, ainsi que des images de commande et de groupe qui racontent une histoire.

Champ d'application de l'autorisation requis

Vous devez ajouter 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: le texte, les lieux et les cartes.

Enrichissements de texte

Un contenu enrichi sous forme de texte peut être inséré pour annoter l'album.

Capture d'écran d'un texte enrichi affiché dans Google Photos

Enrichissements de la position géographique

L'enrichissement par lieu est un repère et le nom d'un lieu qui peut être inséré pour annoter un lieu.

Capture d'écran d'un enrichissement du lieu affiché dans Google Photos

Enrichissements de cartes

Une carte enrichie est une carte avec un point de départ et une destination spécifiés, qui peut être insérée dans l'album.

Capture d'écran d'une carte enrichie affichée dans Google Photos

Positions

Pour insérer des éléments multimédias et des enrichissements d'album, indiquez la position de l'album. La position est facultative pour les éléments multimédias, mais elle doit être spécifiée pour enrichir les albums.

Une position ne peut être spécifiée que lorsque vous créez un élément multimédia ou ajoutez des enrichissements. 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 lors de son 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 comme positionnement absolu.

Par rapport à l'élément multimédia

Un élément multimédia ou d'enrichissement peut être ajouté par rapport à un élément multimédia commençant après sa position dans l'album.

Par rapport à l'article d'enrichissement

Un élément multimédia ou d'enrichissement peut être ajouté par rapport à un élément enrichi à partir de sa position dans l'album.

Ajout de contenus enrichis à un album

Les enrichissements sont ajoutés un par un et doivent être ajoutés à une position dans un album. Pour ajouter des enrichissements à un album, appelez albums.addEnrichment.

Si la requête aboutit, elle renvoie le id de l'article d'enrichissement, qui peut être utilisé pour positionner des éléments multimédias ou d'autres enrichissements.

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 compatibles

Enrichissements de texte

Les enrichissements textuels 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 la position géographique

Les enrichissements de lieux se composent d'un nom de lieu arbitraire et de la latitude et de la longitude. Le champ 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 la carte montrent deux lieux, chacun composé d'un nom et de la latitude et de la longitude. Comme pour l'enrichissement de la zone géographique, le locationName de l'origine et de 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 compatible

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 en dernier à l'utilisateur.

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

La spécification de la position relativeMediaItem fait référence à une position relative à 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'article d'enrichissement

La spécification d'une valeur relativeEnrichmentItemId fait référence à une position relative à un élément d'enrichissement. Les articles sont ajoutés après l'article d'enrichissement spécifié.

REST

{
  "position": "after-enrichment-item",
  "relativeEnrichmentItemId": "enrichment-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);

Modification des enrichissements

Il n'existe actuellement aucun moyen de modifier les enrichissements. Toutefois, une fois qu'un enrichissement a été créé et ajouté à un album, l'utilisateur peut le modifier via l'application Google Photos.