此页面由 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);

地图扩充项

地图扩充项会显示两个位置，每个位置均由名称和纬度组成和经度。与位置扩充项类似，locationName source 和 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);

修改扩充项

目前无法修改扩充项。但是，一旦扩充已创建并添加到影集后，用户可以修改扩充项。