借助扩充功能,您的应用可以控制 Google 相册影集内照片的结构和呈现方式。借助文本或位置注解,您可以为用户提供更多上下文,并对讲述同一个故事的图片进行排序/分组。
所需的授权范围
如需添加扩充项,至少需要以下范围之一:
photoslibrary.appendonly
photoslibrary.library
photoslibrary.sharing
对于每个范围,enrichAlbum
调用仅限于应用创建的影集。
使用 .sharing
范围时,只有开发者代表共享影集的所有者行事时,才能使用 enrichAlbum
。
扩充项类型
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 相册应用修改扩充项。