[Google Photos Library API] JavaでGoogleフォトのメディアアイテム(写真や動画)を検索する

Google Photos Library APIを使用して、
Googleフォトのメディアアイテム(写真や動画)を検索する方法
についてご紹介します。

:::note info
APIを利用する環境の準備から始める場合や、コードを実行する際は、
[⧉[Google Photos Library API(V1)] JavaでPhotos Library APIを使う](https://qiita.com/doran/items/8695e6007765ab5b382c)
を参照ください。
:::

|No||目次|
|---|---|---|
|1||[メディアアイテムを検索](#1-メディアアイテムを検索)|
||1|[スコープ](#11-スコープ)|
||2|[実行](#12-実行)|
||3|[レスポンスの内容](#13-レスポンスの内容)|

## 1. メディアアイテムを検索
メディアアイテム(写真や動画)の検索します。

### 1.1. スコープ
このAPIを実行するには、以下のいずれかのスコープを指定してください。
```
https://www.googleapis.com/auth/photoslibrary
https://www.googleapis.com/auth/photoslibrary.readonly
https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
```
[⧉[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()){
        SearchMediaItemsRequest.Builder builder = SearchMediaItemsRequest.newBuilder();
        builder.setAlbumId("アルバムID");

        SearchMediaItemsPagedResponse response = client.searchMediaItems(builder.build());
        
        for (MediaItem item : response.iterateAll()) {
            System.out.println(item);
        }
    }
}
```
#### 1.2.1. HTTPリクエスト
POST:　https:\//photoslibrary.googleapis.com/v1/mediaItems:search
が実行されます。

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

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

//本来はシンプルにこう書きますが、何かを試すときはあえて分けて書いてます。
//Filters.newBuilder().setIncludeArchivedMedia(true).build()
```
#### SearchMediaItemsRequest
SearchMediaItemsRequest.Builderのsetメソッドにより、
リクエストボディを追加できます。

build()メソッドでSearchMediaItemsRequestインスタンスを取得し、
searchMediaItems()に渡します。

|メソッド|引数|説明|
|---|---|---|
|setAlbumId|String|アルバムID<br>setFilters()と同時に設定することは不可|
|setPageSize|Integer|レスポンスで返すメディアイアテムの最大数<br>デフォルトは25、最大は100|
|setPageToken|String|結果の次のページを取得するための連続トークン|
|setFilters|[Filters](#filters)|リクエストに適用するフィルタ<br>setAlbumId()と同時に設定することは不可|
|setOrderBy|String|結果の並べ替え<br>setFilters()でsetDateFilter()を設定している場合のみ有効<br><br>"MediaMetadata.creation_time"(作成日が古い順)<br>"MediaMetadata.creation_time desc"(作成日が新しい順)|

#### Filters
|メソッド|引数|説明|
|---|---|---|
|setDateFilter|[DateFilter](#datefilter)|作成日フィルタ|
|setContentFilter|[ContentFilter](#contentfilter)|コンテンツフィルタ|
|setMediaTypeFilter|[MediaTypeFilter](#mediatypefilter)|メディアタイプフィルタ|
|setFeatureFilter|[FeatureFilter](#featurefilter)|機能フィルタ|
|setIncludeArchivedMedia|Boolean|ユーザーがアーカイブしたメディアアイテムか|
|setExcludeNonAppCreatedData|Boolean|このAPI以外で設定したメディアアイテムか|

#### DateFilter
|メソッド|引数|説明|
|---|---|---|
|addDates|Date|作成日と一致する日付のリスト<br>最大５つ|
|addRanges|[DateRange](#daterange)|作成日と一致する期間のリスト<br>最大5つ|

#### ContentFilter
|メソッド|引数|説明|
|---|---|---|
|addIncludedContentCategories|[ContentCategory(enum)](#contentcategory)|結果に含めるカテゴリセット<br>最大10つ|
|addExcludedContentCategories|[ContentCategory(enum)](#contentcategory)|結果に含めないカテゴリセット<br>最大10つ|

#### MediaTypeFilter
|メソッド|引数|説明|
|---|---|---|
|addMediaTypes|[MediaType(enum)](#mediatype)|アイテムタイプ<br>最大1つ|

#### FeatureFilter
|メソッド|引数|説明|
|---|---|---|
|addIncludedFeatures|[Feature(enum)](#feature)|機能セット|

#### DateRange
|メソッド|引数|説明|
|---|---|---|
|setStartDate|Date|開始日（期間の一部として含める）|
|setEndDate|Date|終了日（期間の一部に含まれます）|

#### ContentCategory
|定義値|内容|
|---|---|
|NONE|デフォルトのコンテンツカテゴリ|
|LANDSCAPES|風景を含むメディアアイテム|
|RECEIPTS|領収書を含むメディアアイテム|
|CITYSCAPES|都市景観を含むメディアアイテム|
|LANDMARKS|ランドマークを含むメディアアイテム|
|SELFIES|自撮り写真のメディアアイテム|
|PEOPLE|人物を含むメディアアイテム|
|PETS|ペットを含むメディアアイテム|
|WEDDINGS|結婚式のメディアアイテム|
|BIRTHDAYS|誕生日のメディアアイテム|
|DOCUMENTS|ドキュメントを含むメディアアイテム|
|TRAVEL|旅行中に撮影されたメディアアイテム|
|ANIMALS|動物を含むメディアアイテム|
|FOOD|食品を含むメディアアイテム|
|SPORT|スポーツ|イベントのメディアアイテム|
|NIGHT|夜間に撮影されたメディアアイテム|
|PERFORMANCES|公演のメディアアイテム|
|WHITEBOARDS|ホワイトボードを含むメディアアイテム|
|SCREENSHOTS|スクリーンショットのメディアアイテム|
|UTILITY|有用とみなされるメディアアイテム|
|ARTS|アートを含むメディアアイテム|
|CRAFTS|工芸を含むメディアアイテム|
|FASHION|ファッションに関連するメディアアイテム|
|HOUSES|家を含むメディアアイテム|
|GARDENS|庭園を含むメディアアイテム|
|FLOWERS|花を含むメディアアイテム|
|HOLIDAYS|休日に撮影されたメディアアイテム|

#### MediaType
|定義値|内容|
|---|---|
|ALL_MEDIA|すべてのメディアタイプ|
|VIDEO|動画|
|PHOTO|写真|

#### Feature
|定義値|内容|
|---|---|
|NONE|すべての機能|
|FAVORITES|Googleフォトでお気に入りとしてマーク|

### 1.3. レスポンスの内容
#### SearchMediaItemsPagedResponse
|メソッド|戻り値|説明|
|---|---|---|
|iterateAll|Iterable\<[MediaItem](#mediaitem)\>|メディアアイテムのリスト|
|getNextPageToken|String|メディアアイテムの次のセットを取得するためのトークン|

#### MediaItem
|メソッド|戻り値|説明|
|---|---|---|
|getId|String|メディアアイテムID|
|getDescription|String|メディアアイテムの説明|
|getProductUrl|String|メディアアイテムの GoogleフォトURL|
|getBaseUrl|String|メディアアイテムのバイトへのURL|
|getMimeType|String|メディアアイテムのMIMEタイプ|
|getMediaMetadata|[MediaMetadata](#mediametadata)|メディアアイテムに関連するメタデータ|
|getContributorInfo|[ContributorInfo](#contributorinfo)|メディアアイテムを追加したユーザーの情報|
|getFilename|String|メディアアイテムのファイル名|

#### MediaMetadata
|メソッド|戻り値|説明|
|---|---|---|
|getCreationTime|Timestamp|メディアアイテムが最初に作成された時刻|
|getWidth|Long|メディアアイテムの元の幅（ピクセル単位）|
|getHeight|Long|メディアアイテムの元の高さ（ピクセル単位）|
|getPhoto|[Photo](#photo)|写真のメディアタイプのメタデータ|
|getVideo|[Video](#video)|動画のメディアタイプのメタデータ|

#### Photo
|メソッド|戻り値|説明|
|---|---|---|
|getCameraMake|String|写真を撮影したカメラのブランド|
|getCameraModel|String|写真を撮影したカメラのモデル|
|getFocalLength|Float|写真を撮影したカメラのレンズの焦点距離|
|getApertureFNumber|Float|写真を撮影したカメラレンズの絞りのf値|
|getIsoEquivalent|Integer|写真を撮影したカメラのISO|
|getExposureTime|Duration|写真が撮影されたときのカメラの絞りの露出時間|

#### Video
|メソッド|戻り値|説明|
|---|---|---|
|getCameraMake|String|動画を撮影したカメラのブランド|
|getCameraModel|String|動画を撮影したカメラのモデル|
|getFps|Double|動画のフレームレート|
|getStatus|[VideoProcessingStatus(enum)](#videoprocessingstatus)|動画の処理ステータス|

#### ContributorInfo
|メソッド|戻り値|説明|
|---|---|---|
|getProfilePictureBaseUrl|String|投稿者のプロフィール写真のURL|
|getDisplayName|String|表示名|

#### VideoProcessingStatus
|定義値|内容|
|---|---|
|UNSPECIFIED|動画の処理ステータスが不明|
|PROCESSING|動画の処理中|
|READY|動画の処理が完了し、表示できるようになった|
|FAILED|エラーが発生したため、動画を処理できなかった|

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