Dodaj wzbogacenia

Dzięki wzbogacaniom aplikacja może kontrolować strukturę i prezentację zdjęć w albumie w Zdjęciach Google. Umożliwiają przedstawienie użytkownikowi dodatkowego kontekstu za pomocą tekstu lub adnotacji lokalizacji oraz obrazów kolejności/grup, które razem opowiadają historię.

Wymagany zakres autoryzacji

Aby dodać wzbogacenia, wymagany jest co najmniej jeden z tych zakresów:

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

W przypadku każdego zakresu wywołanie enrichAlbum jest ograniczone do albumów utworzonych przez aplikację.

Gdy używany jest zakres .sharing, usługa enrichAlbum jest dostępna tylko w sytuacjach, gdy deweloper działa w imieniu właściciela albumu udostępnionego.

Typy wzbogacania

Zdjęcia Google obsługują w albumach 3 rodzaje wzbogaceń: tekst, lokalizacje i mapy.

Wzbogacanie tekstu

Wzbogacanie tekstu to zwykły ciąg tekstowy, który można wstawić, aby dodać do albumu adnotacje.

Zrzut ekranu wzbogaconego tekstu w Zdjęciach Google

Wzbogacanie informacji o lokalizacji

Uwzględnienie lokalizacji to znacznik i nazwa miejsca, które można wstawić, aby dodać do niej adnotację.

Zrzut ekranu ze wzbogaconymi informacjami o lokalizacji widoczny w Zdjęciach Google

Udoskonalenia map

Wzbogacanie mapy to mapa z określonym punktem początkowym i docelowym, które można wstawić do albumu.

Zrzut ekranu przedstawiający wzbogacenie mapy wyświetlane w Zdjęciach Google

Pozycje

Aby wstawić elementy multimedialne i ulepszenia z albumu, określ jego pozycję. Pozycja jest opcjonalna w przypadku elementów multimedialnych, ale musi być określona na potrzeby wzbogacania albumu.

Położenie można określić tylko podczas tworzenia elementu multimedialnego lub dodawania wzbogaceń. Nie można porządkować dotychczasowych elementów multimedialnych w albumie, dlatego ważne jest ustawienie pozycji elementu podczas dodawania.

Początek albumu

Elementy multimedialne/wzbogacające można dodać na początku albumu w określeniu absolutnym.

Koniec albumu

Elementy multimedialne/wzbogacające można dodać na końcu albumu w określeniu bezwzględnym.

Względem elementu multimedialnego

Element multimedialny lub wzbogacający można dodać względem elementu multimedialnego, który rozpoczyna się po jego pozycji w albumie.

Względem elementu wzbogacającego

Element multimedialny lub wzbogacający można dodać względem elementu wzbogacającego, który zaczyna się po jego pozycji w albumie.

Dodawanie wzbogaceń do albumu

Wzbogacenia są dodawane pojedynczo do pozycji w albumie. Aby dodać wzbogacenia do albumu, wywołaj metodę albums.addEnrichment.

Jeśli żądanie zostanie zrealizowane, zwróci wartość id elementu wzbogacającego, której można użyć do pozycjonowania elementów multimedialnych lub innych ulepszeń.

REST

Oto żądanie POST:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment
Content-type: application/json
Authorization: Bearer oauth2-token
request-body

Treść żądania składa się z elementu wzbogacającego i jego pozycji:

{
  "newEnrichmentItem": {
    enrichment-to-be-added
  },
  "albumPosition": {
    position-of-enrichment
}

Przykładowa odpowiedź:

{
  "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
}

Obsługiwane wzbogacenia

Wzbogacanie tekstu

Wzbogacanie tekstu składa się z pojedynczego ciągu tekstowego (maksymalnie 1000 znaków), tak jak w tym przykładzie:

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");

Wzbogacanie informacji o lokalizacji

Dane o lokalizacji składają się z dowolnej nazwy lokalizacji oraz szerokości i długości geograficznej. Pole locationName może zawierać maksymalnie 500 znaków.

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);

Udoskonalenia map

Wzbogacenia mapy pokazują 2 lokalizacje, z których każda składa się z nazwy oraz szerokości i długości geograficznej. Podobnie jak w przypadku wzbogacania danych o lokalizację, pole locationName w źródłowym i destination może mieć maksymalnie 500 znaków.

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);

Obsługiwane pozycjonowanie

Początek albumu

Pozycja FIRST_IN_ALBUM oznacza początek albumu. Użytkownikom wyświetla się najpierw te elementy:

REST

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);

Koniec albumu

Pozycja LAST_IN_ALBUM oznacza koniec albumu. Znajdujące się tu elementy są wyświetlane na końcu.

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::LAST_IN_ALBUM);

Względem elementu multimedialnego

Określenie pozycji relativeMediaItem odnosi się do pozycji względem elementu multimedialnego. Elementy są dodawane po określonym elemencie multimedialnym.

REST

{
  "position": "after-media-item",
  "relativeMediaItemId": "media-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);

Względem elementu wzbogacającego

Określenie relativeEnrichmentItemId odnosi się do pozycji względem elementu wzbogacającego. Elementy są dodawane po określonym elemencie wzbogacającym.

REST

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

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

Modyfikowanie wzbogaceń

Obecnie nie można modyfikować wzbogaceń. Po utworzeniu wzbogacenia i dodaniu go do albumu użytkownik może je zmodyfikować w aplikacji Zdjęcia Google.