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

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

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

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

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

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

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

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

В альбомы 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",
  }
}

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
}

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

Обогащение текста

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