Добавить дополнения

Расширения позволяют вашему приложению управлять структурой и представлением фотографий в альбоме Google Фото. Они позволяют предоставить пользователю дополнительный контекст посредством текстовых аннотаций или аннотаций местоположений, а также изображений в порядке/группировке, которые вместе рассказывают историю.

Требуемая область авторизации

Чтобы добавить дополнения, требуется хотя бы одна из следующих областей:

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

Для каждой области вызов enrichAlbum ограничен только альбомами, созданными приложением.

При использовании области .sharing enrichAlbum ограничивается обстоятельствами, когда разработчик действует от имени владельца общего альбома.

Типы обогащения

Google Фото поддерживает три типа дополнений в альбомах: текст, местоположения и карты.

Текстовые дополнения

Текстовое дополнение — это обычная текстовая строка, которую можно вставить для аннотации к альбому.

Снимок экрана с текстовым дополнением в Google Фото

Улучшения локаций

Дополнение к местоположению — это маркер и название места, которые можно вставить для аннотации к местоположению.

Скриншот уточнения местоположения в Google Фото

Дополнения карты

Дополнение к карте — это карта с указанным пунктом отправления и пункта назначения, которую можно вставить в альбом.

Скриншот дополненной карты в Google Фото

Позиции

Чтобы вставить элементы мультимедиа и дополнения к альбому, укажите положение альбома. Позиция не является обязательной для элементов мультимедиа, но ее необходимо указать для пополнения альбома.

Позицию можно указать только при создании элемента мультимедиа или добавлении дополнений. Существующие элементы мультимедиа в альбоме нельзя реорганизовать, поэтому важно задать положение элемента при его добавлении.

Начало альбома

Элемент мультимедиа/дополнения можно добавить в начало альбома как абсолютное позиционирование.

Конец альбома

Элемент мультимедиа/дополнения можно добавить в конец альбома в качестве абсолютного позиционирования.

Относительно медиа-элемента

Элемент мультимедиа/дополнения можно добавить относительно элемента мультимедиа, начиная с его позиции в альбоме.

Относительно предмета обогащения

Медиа/дополнительный элемент можно добавить относительно дополнительного элемента, начиная с его позиции в альбоме.

Добавление дополнений в альбом

Дополнения добавляются по одному и должны быть добавлены в определенную позицию в альбоме. Чтобы добавить дополнения в альбом, вызовите albums.addEnrichment .

Если запрос успешен, он возвращает id элемента дополнения, который можно использовать для позиционирования элементов мультимедиа или других дополнений.

ОТДЫХ

Вот POST-запрос:

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

Тело запроса состоит из элемента дополнения и его позиции:

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

Вот пример ответа:

{
  "enrichmentItem": {
    "id": "enrichment-item-id",
  }
}

Ява 

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
}

Поддерживаемые дополнения

Текстовые дополнения

Текстовые дополнения содержат одну текстовую строку (не более 1000 символов), как показано в следующем примере:

ОТДЫХ 

{
  "text": "Text to be shown"
}

Ява 

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

Улучшения локаций

Расширение местоположения состоит из произвольного названия местоположения и положения широты и долготы. locationName ограничено 500 символами.

ОТДЫХ 

{
  "location": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  }
}

Ява 

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

Дополнения карты

В дополнении к карте показаны два местоположения, каждое из которых содержит название, а также широту и долготу. Как и при дополнении местоположения, locationName в исходной и destination ограничен 500 символами.

ОТДЫХ 

{
  "origin": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  },
  "destination": {
    "locationName": "San Francisco",
    "latlng": {
      "latitude": "37.757",
      "longitude": "122.507"
    }
  }
}

Ява 

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

Поддерживаемое позиционирование

Начало альбома

Позиция FIRST_IN_ALBUM относится к началу альбома. Расположенные здесь элементы показываются пользователю в первую очередь:

ОТДЫХ 

{
  "position": "FIRST_IN_ALBUM",
}

Ява 

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP 

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

Конец альбома

Позиция LAST_IN_ALBUM относится к концу альбома. Расположенные здесь элементы показываются пользователю в последнюю очередь.

ОТДЫХ 

{
  "position": "LAST_IN_ALBUM",
}

Ява 

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP 

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

Относительно медиа-элемента

Указание relativeMediaItem относится к позиции относительно элемента мультимедиа. Элементы добавляются после указанного элемента мультимедиа.

ОТДЫХ 

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

Ява 

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP 

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

Относительно предмета обогащения

Указание relativeEnrichmentItemId относится к позиции относительно элемента обогащения. Элементы добавляются после указанного элемента обогащения.

ОТДЫХ 

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

Ява 

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP 

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

Изменение дополнений

В настоящее время нет возможности изменить обогащения. Однако после того, как дополнение было создано и добавлено в альбом, пользователь может изменить его через приложение Google Photos.