豐富功能可讓應用程式控制 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 }
支援的擴充功能
文字多元化
文字充實內容包含一個文字字串 (不得超過 1,000 個字元),如以下範例所示:
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 相簿應用程式修改豐富內容。