添加扩充项

扩展项可以让您的应用控制照片在 Google 相册影集中的结构和呈现方式。利用扩展项，您可以通过文本或位置注释向用户展示其他内容，并对讲述同一故事的图片进行排序/分组。

必需的授权范围

如需向应用创建的影集添加丰富内容，需要 photoslibrary.appendonly 范围。如需详细了解镜，请参阅授权范围。

扩充项类型

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

地图扩充项

地图扩充项会显示两个位置，每个位置都由名称以及经纬度组成。与位置扩充项类似，源站和 destination 中的 locationName 限制为 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 相册应用修改扩充项。