[Google Photos Library API] JavaでGoogleフォトのアルバムにエンリッチメントを追加する

Google Photos Library APIを使用して、
Googleフォトのアルバムにエンリッチメントを追加する方法
についてご紹介します。

**Googleフォトのエンリッチメントとは**
アルバムにいろいろな情報を紐づけることでアルバムのグルーピングが行えます。

Googleフォトのエンリッチメントは、テキスト、位置情報、地図の 3種類に対応しています。
|エンリッチメント|内容|UIの場所|
|---|---|---|
|テキスト|アルバムにアノテーションを付けるために挿入できる書式なしテキストの文字列|<img width=120 src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/114621/d0c3ff4e-c07c-6105-680d-866163acb563.png">|
|位置情報|場所にアノテーションを付けるために挿入できる場所の名前|<img width=120 src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/114621/d9a890fc-aaa9-3a93-b711-68777233c9a8.png">|
|地図|アルバムに挿入できる出発地と目的地を指定した地図|<img width=120 src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/114621/ecb981f7-bc01-46ca-8d2f-b17f83b07aa3.png">|

エンリッチメントの追加が可能なアルバムは
同じGCP認証、かつGoogle Docs API V1で作成したアルバムのみです。

アルバムの作成方法は
[⧉[Google Photos Library API] JavaでGoogleフォトのアルバムを作成・更新する](https://qiita.com/doran/items/b5ecc7005f19fbf0a35a)
を参照ください。

:::note info
APIを利用する環境の準備から始める場合や、コードを実行する際は、
を参照ください。
:::

|No||目次|
|---|---|---|
|1||[エンリッチメントを追加](#1-エンリッチメントを追加)|
||1|[スコープ](#11-スコープ)|
||2|[実行](#12-実行)|
||3|[レスポンスの内容](#13-レスポンスの内容)|

## 1. エンリッチメントを追加
指定のアルバムにエンリッチメントを追加します。

エンリッチメントの追加が可能なアルバムは
同じGCP認証、かつGoogle Docs API V1で作成したアルバムのみです。

### 1.1. スコープ
このAPIを実行するには、以下のいずれかのスコープを指定してください。
```
https://www.googleapis.com/auth/photoslibrary
https://www.googleapis.com/auth/photoslibrary.appendonly
https://www.googleapis.com/auth/photoslibrary.sharing
```
[⧉[Google Photos Library API(V1)] JavaでPhotos Library APIを使う(2.2. PhotosLibraryClientインスタンスを取得)](https://qiita.com/doran/items/8695e6007765ab5b382c#22-photoslibraryclientインスタンスを取得)
でスコープを指定してください。

### 1.2. 実行

```java
public static void main(String[] args) throws Exception{
    try(PhotosLibraryClient client = getPhotosLibraryClient()){
        NewEnrichmentItem.Builder item_builder =  NewEnrichmentItem.newBuilder();
        AlbumPosition.Builder position_builder = AlbumPosition.newBuilder();

        AddEnrichmentToAlbumResponse response = client.addEnrichmentToAlbum("アルバムID",item_builder.build(),position_builder.build());
        System.out.println(response.getEnrichmentItem().getId());
    }
}
```
#### 1.2.1. HTTPリクエスト
POST:　https:\//photoslibrary.googleapis.com/v1/albums/{アルバムID}:addEnrichment
が実行されます。

#### 1.2.2. クエリパラメータ
クエリパラメータはありません。

#### 1.2.3. リクエストボディ
引数で渡す各インスタンス(com.google.photos.library.v1.protoパッケージ)は
各クラスのstaticで用意されているnewBuilder()でBuilderクラスを取得します。
Builderクラスに対してsetメソッドで値を設定し、build()でインスタンスを取得します。
```java
//例
//newBuilder()で各Builderクラスを取得
TextEnrichment.Builder builder = TextEnrichment.newBuilder();
//Builderクラスのsetメソッドで値を設定
builder.setText("テキスト");
//build()メソッドでインスタンスを取得
TextEnrichment text = builder.build();

//本来はシンプルにこう書きますが、何かを試すときはあえて分けて書いてます。
//TextEnrichment.newBuilder().setText("テキスト").build()
```
アルバムID、エンリッチメント、挿入位置の3つをリクエストボディに設定します。
全て必須です。

#### 1.2.3.1. アルバムID
エンリッチメントを追加するアルバムIDを指定します。

#### 1.2.3.2. エンリッチメント
追加するエンリッチメントを指定します。
#### NewEnrichmentItem
|メソッド|引数|説明|
|---|---|---|
|setTextEnrichment|[TextEnrichment](#textenrichment)|アルバムに追加するテキスト|
|setLocationEnrichment|[LocationEnrichment](#locationenrichment)|アルバムに追加する場所|
|setMapEnrichment|[MapEnrichment](#mapenrichment)|アルバムに追加する地図|

#### TextEnrichment
|メソッド|引数|説明|
|---|---|---|
|setText|String|アイテムのテキスト|

#### LocationEnrichment
|メソッド|引数|説明|
|---|---|---|
|setLocation|[Location](#Location)|アイテムの場所|

#### Location
|メソッド|引数|説明|
|---|---|---|
|setLocationName|String|表示するビジネスの名前|
|setLatlng|[LatLng](#latlng)|地図上の場所の位置|

#### LatLng
|メソッド|引数|説明|
|---|---|---|
|setLatitude|double|緯度（度単位）(-90.0〜90.0)|
|setLongitude|double|経度（度単位）(-180.0〜180.0|

#### MapEnrichment
|メソッド|引数|説明|
|---|---|---|
|setOrigin|[Location](#Location)|アイテムの出発地|
|setDestination|[Location](#Location)|アイテムの目的地|

#### 1.2.3.3. 挿入位置
エンリッチメントを挿入する位置を指定します。
#### AlbumPosition
|メソッド|引数|説明|
|---|---|---|
|setPosition|[PositionType(enum)](#positiontype)|アイテムの位置タイプ|
|setRelativeMediaItemId|String|【setPosition(PositionType.AFTER_MEDIA_ITEM)の場合のみ必須】<br><br>位置の基準となるメディアアイテムID|
|setRelativeEnrichmentItemId|String|【setPosition(PositionType.AFTER_ENRICHMENT_ITEM)の場合のみ必須】<br><br>位置の基準となるエンリッチメントアイテムID|

#### PositionType
|定義値|内容|
|---|---|
|POSITION_TYPE_UNSPECIFIED|設定なし|
|FIRST_IN_ALBUM|アルバムの先頭|
|LAST_IN_ALBUM|アルバムの最後|
|AFTER_MEDIA_ITEM|メディアアイテムの後|
|AFTER_ENRICHMENT_ITEM|エンリッチメントアイテムの後|


### 1.3. レスポンスの内容
#### AddEnrichmentToAlbumResponse
|メソッド|戻り値|説明|
|---|---|---|
|getEnrichmentItem|[EnrichmentItem](#enrichmentitem)|追加されたエンリッチメント|

#### EnrichmentItem
|メソッド|戻り値|説明|
|---|---|---|
|getId|String|エンリッチメントアイテムID|

<br>
<br>
おしまい。。