Adicionar enriquecimentos

Os enriquecimentos permitem que seu aplicativo controle a estrutura e a apresentação fotos em um álbum no Google Fotos. Eles permitem que você apresente ao usuário com mais contexto por meio de anotações de texto ou localização e ordem/grupo imagens que contam uma história juntas.

Escopo de autorização obrigatório

Para adicionar aprimoramentos, é necessário pelo menos um dos seguintes escopos:

  • photoslibrary.appendonly
  • photoslibrary.library
  • photoslibrary.sharing

Para cada escopo, a chamada enrichAlbum é restrita apenas aos álbuns criados pelo app.

Ao usar o escopo .sharing, o enrichAlbum é restrito às circunstâncias em que o desenvolvedor atua em nome do proprietário do álbum compartilhado.

Tipos de enriquecimento

O Google Fotos é compatível com três tipos de melhorias em álbuns: texto, locais e mapas.

Aprimoramentos de texto

Um enriquecimento de texto é uma string de texto simples que pode ser inserida para anotar a álbum.

Captura de tela de um aprimoramento de texto mostrado no Google Fotos

Aprimoramentos de local

Um aprimoramento 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 mostrado no Google Fotos

Aprimoramentos do mapa

Um aprimoramento do mapa é um mapa com uma origem e um destino especificados que podem ser inserida no álbum.

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

Posições

Para inserir itens de mídia e enriquecimentos de álbum, especifique a posição do álbum. Uma posição é opcional para itens de mídia, mas deve ser especificada para o álbum de enriquecimento.

Só é possível especificar uma posição Como criar um item de mídia ou adicionar aperfeiçoamentos. 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 for adicionado.

Início do álbum

Um item de mídia/enriquecimento pode ser adicionado ao início do álbum como absoluto de posicionamento.

Fim do álbum

Um item de mídia/enriquecimento pode ser adicionado ao final do álbum como absoluto. de posicionamento.

Relativo ao item de mídia

Um item de mídia/enriquecimento pode ser adicionado em relação a um item de mídia que começa depois de sua posição no álbum.

Relativo ao item de aprimoramento

Um item de mídia/enriquecimento pode ser adicionado em relação a um item de aprimoramento que começa com depois de sua posição no álbum.

Adicionando aprimoramentos ao álbum

Os aprimoramentos são adicionados um de cada vez e precisam ser adicionados a 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 podem ser usados para posicionar itens de mídia ou outras melhorias.

REST

Aqui está 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
}

Melhorias com suporte

Aprimoramentos de texto

Os aprimoramentos de texto contêm uma única string de texto (no máximo 1.000 caracteres), conforme como mostrado no exemplo a seguir:

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

Os aprimoramentos de local consistem em um nome de local arbitrário e a latitude e longitude. O locationName está 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 do mapa

Os aprimoramentos do mapa mostram dois locais, cada um consistindo em um nome e a latitude e longitude. Semelhante ao aprimoramento de local, o locationName no origem e destination tem um limite de 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. Itens localizados são mostrados ao usuário primeiro:

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 final do álbum. 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 aprimoramento

A especificação de um relativeEnrichmentItemId refere-se a uma posição relativa a um item de aprimoramento. 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 aprimoramentos

No momento, não é possível modificar as melhorias. No entanto, quando um enriquecimento for criada e adicionada a um álbum, o usuário poderá modificar as melhorias pelo app Google Fotos.