添加扩充项

扩充项可让您的应用控制 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);

修改扩充项

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