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

エンリッチメントを使用すると、Google フォトのアルバム内にある写真の構造と表示方法をアプリケーションで管理できます。テキストや場所の注釈、画像の順序やグループ化を使用してストーリーを伝え、ユーザーに追加のコンテキストを提示できます。

必要な認可スコープ

アプリによって作成されたアルバムにエンリッチメントを追加するには、photoslibrary.appendonly スコープが必要です。スコープの詳細については、認可スコープをご覧ください。

拡充の種類

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

サポートされているエンリッチメント

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

テキストのエンリッチメントには、次の例に示すように、単一のテキスト文字列（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 つの場所が表示され、それぞれが名前、緯度と経度で構成されます。場所のエンリッチメントと同様に、開始地点と 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 フォト アプリでエンリッチメントを変更できます。