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

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

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

Для добавления дополнений в альбомы, созданные приложением, требуется область photoslibrary.appendonly . Дополнительные сведения об областях см. в разделе Области авторизации .

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

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

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

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

Текстовые дополнения содержат одну текстовую строку (не более 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.