エンリッチメントを追加する

エンリッチメントを使用すると、Google フォトのアルバム内の写真の構造と表示方法をアプリで制御できます。テキストや場所のアノテーション、画像の順序付けやグループ化によって、ストーリーを伝えます。

必要な認可スコープ

エンリッチメントを追加するには、次のスコープのうち少なくとも 1 つが必要です。

  • photoslibrary.appendonly
  • photoslibrary.library
  • photoslibrary.sharing

各スコープで、enrichAlbum 呼び出しはアプリによって作成されたアルバムのみに制限されます。

.sharing スコープを使用する場合、enrichAlbum は、デベロッパーが共有アルバムのオーナーに代わって操作している状況に限定されます。

拡充の種類

Google フォトは、テキスト、位置情報、地図の 3 種類のアルバムのエンリッチメントに対応しています。

テキストのエンリッチメント

テキスト エンリッチメントは、アルバムにアノテーションを付けるために挿入できる書式なしテキストの文字列です。

Google フォトに表示されているテキスト エンリッチメントのスクリーンショット

位置情報のエンリッチメント

場所のエンリッチメントはマーカーであり、その場所にアノテーションを付けるために挿入できる場所の名前です。

Google フォトに表示された位置情報のエンリッチメントのスクリーンショット

地図のエンリッチメント

地図のエンリッチメントは、アルバムに挿入できる出発地と目的地を指定した地図です。

Google フォトに表示されている地図のエンリッチメントのスクリーンショット

位置

メディア アイテムとアルバムのエンリッチメントを挿入するには、アルバムの位置を指定します。メディア アイテムの位置は省略可能ですが、アルバムを拡充する場合は位置を指定する必要があります。

位置を指定できるのは、メディア アイテムを作成するとき、またはエンリッチメントを追加するときのみです。アルバム内の既存のメディア アイテムは再編成できないため、アイテムを追加するときにその位置を設定することが重要です。

アルバムの先頭

メディア アイテムやエンリッチメント アイテムは、絶対位置としてアルバムの先頭に追加できます。

アルバムの最後

メディア アイテムやエンリッチメント アイテムは、絶対位置としてアルバムの最後に追加できます。

メディア アイテムに相対

メディア アイテムやエンリッチメント アイテムは、アルバム内での位置より後から始まるメディア アイテムに対して追加できます。

エンリッチメント アイテムに関連

メディア アイテムやエンリッチメント アイテムは、アルバム内のエンリッチメント アイテムの位置以降、相対的に追加できます。

アルバムにエンリッチメントを追加しています

エンリッチメントは一度に 1 つずつ追加し、アルバム内の位置に追加する必要があります。アルバムにエンリッチメントを追加するには、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 つのテキスト文字列（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);

地図のエンリッチメント

地図のエンリッチメントには 2 つの場所が表示され、それぞれ名前と緯度と経度で構成されます。位置情報のエンリッチメントと同様に、origin と 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 フォト アプリでエンリッチメントを変更できます。