Adicionar enriquecimentos

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.

Captura de tela de um enriquecimento de texto exibido no Google Fotos

Aprimoramentos de local

Um enriquecimento de local é um marcador e o nome do lugar que pode ser inserido para anotar um local.

Captura de tela de um aprimoramento de local exibido no Google Fotos

Aprimoramentos de mapas

Um aprimoramento de mapa é aquele com uma origem e um destino especificados que podem ser inseridos no álbum.

Captura de tela de um aprimoramento do mapa exibido no Google Fotos

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.