此页面由 Cloud Translation API 翻译。

添加扩充项

借助扩充功能，您的应用可以控制 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);

地图扩充项

地图扩充项会显示两个位置，每个位置均包含名称和经纬度。与位置扩充项类似，出发地和 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 相册应用修改扩充项。