新增充實內容

應用程式可透過豐富內容功能，控管 Google 相簿相簿中相片的結構和呈現方式。您可以透過文字或位置註解，以及可共同講述故事的圖片順序/群組，向使用者提供其他背景資訊。

必要的授權範圍

如要為應用程式建立的相簿新增強化功能，您必須具備 photoslibrary.appendonly 範圍。如要進一步瞭解範圍，請參閱「授權範圍」。

充實類型

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",
  }
}

支援的強化功能

文字擴充

文字強化內容包含單一文字字串 (最多 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 相簿應用程式修改強化內容。