本頁面由 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
}

支援的擴充功能

文字多元化

文字充實內容包含一個文字字串 (不得超過 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 相簿應用程式修改豐富內容。