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

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

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

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

Типы дополнений

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

Дополнения к тексту

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

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

Дополнительные данные о местоположении

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

Скриншот с информацией о месте съемки в Google Фото

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

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

Скриншот карты в Google Фото

Позиции

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

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

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

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

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

Объект или элемент обогащения можно добавить в конец альбома, указав абсолютную позицию.

Относительно мультимедийного объекта

Мультимедийный объект или элемент обогащения можно добавить относительно мультимедийного объекта, который находится после него в альбоме.

Относительно объекта обогащения

Объект медиа или объект обогащения можно добавить относительно начала объекта обогащения после его позиции в альбоме.

Добавление объектов в альбом…

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

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

REST

Пример запроса 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 символов), как показано в следующем примере:

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

Дополнительные данные о местоположении

Дополнение с местоположением состоит из произвольного названия места и его координат (широты и долготы). locationName не может содержать более 500 символов.

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

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

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

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

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

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

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

REST

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

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

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

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

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

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

Относительно мультимедийного объекта

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

REST

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

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

Относительно объекта обогащения

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

REST

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

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

Изменение обогащений

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