[Cloud Storage API(V2)] Javaでオブジェクトの情報を取得する

Cloud Storage API V2(Java)を使用して、
Cloud Storageのオブジェクトのメタデータを取得する方法
についてご紹介します。

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

|No|||目次|
|---|---|---|---|
|1|||[オブジェクト一覧を取得](#1-オブジェクト一覧を取得)|
||1||[スコープ](#11-スコープ)|
||2||[実行](#12-実行)|
||3||[レスポンスの内容](#13-レスポンスの内容)|
||4||[オブジェクト一覧のパラメータの指定例](#14-オブジェクト一覧のパラメータの指定例)|
|||1|[全てのオブジェクトを取得](#141-全てのオブジェクトを取得)|
|||2|[ルート階層配下のみを取得](#142-ルート階層配下のみを取得)|
|||3|[指定フォルダ配下のみ取得](#143-指定フォルダ配下のみ取得)|
|2|||[オブジェクトを取得](#2-オブジェクトを取得)|
||1||[スコープ](#21-スコープ)|
||2||[実行](#22-実行)|
||3||[レスポンスの内容](#13-レスポンスの内容)|

## 1. オブジェクト一覧を取得
指定したバケットのオブジェクト一覧を取得します。

### 1.1. スコープ
このAPIを実行するには、以下のいずれかのスコープを指定してください。
```
StorageScopes.CLOUD_PLATFORM
StorageScopes.CLOUD_PLATFORM_READ_ONLY
StorageScopes.DEVSTORAGE_FULL_CONTROL
StorageScopes.DEVSTORAGE_READ_ONLY
StorageScopes.DEVSTORAGE_READ_WRITE
```
[⧉[Cloud Storage API(V2)] JavaでCloud Storageを使う(2.2 Storageインスタンスを取得)](https://qiita.com/doran/items/2a5f7ef8070fd5b8c94d#22-storageインスタンスを取得)
でスコープを指定してください。

### 1.2. 実行

```java
public static void main(String[] args) throws Exception{
    Storage storage = getStorage();
    Storage.Objects objects = storage.objects();
    
    Storage.Objects.List list = objects.list("バケットID");
    
    Objects res = list.execute();
    System.out.println(res);
}
```
#### 1.2.1. HTTPリクエスト
GET:　https:\//storage.googleapis.com/storage/v1/b/{バケットID}/o
が実行されます。

#### 1.2.2. クエリパラメータ
Storage.Objects.Listのsetメソッドにより、クエリパラメータを追加できます。

|メソッド|引数|説明|
|---|---|---|
|setMaxResults|Long|取得するオブジェクトの最大数<br>最大:1000|
|setPageToken|String|取得するページトークン|
|setDelimiter|String|オブジェクト名をここで指定した文字を「区切り文字」として分割する。<br><br>オブジェクト名は、フォルダ階層がある場合は"/"が使用されるので、通常はフォルダで区切りたい場合は"/"を使用する|
|setIncludeFoldersAsPrefixes|Boolean|【setDelimiter("/")を指定した場合のみ】<br><br>取得結果のgetPrefixes()に管理フォルダーも結果に含めるか|
|setIncludeTrailingDelimiter|Boolean|setDelimiter()で指定した値を含むオブジェクト名をgetItems()で取得するか|
|setMatchGlob|String|取得結果のフィルタに使用する[ワイルドカード](#globパターン)。<br><br>オブジェクト名が指定した[ワイルドカードにマッチする](#globパターン)オブジェクトだけを受け取る|
|setPrefix|String|取得結果のフィルタに使用するオブジェクト名のプレフィックス(接頭語)。<br><br>指定したオブジェクト名のプレフィックスで始まるオブジェクト名のオブジェクトだけを受け取る|
|setStartOffset|String|取得結果のフィルタに使用する開始オブジェクト名。<br><br>オフジェクト名を昇順で並べ、指定したオブジェクト名より後のリストを結果として受け取る。<br>(開始オブジェクト名を含む)|
|setEndOffset|String|取得結果のフィルタに使用する終了オブジェクト名。<br><br>オフジェクト名を昇順で並べ、指定したオブジェクト名より前のリストを結果として受け取る。<br>(終了オブジェクト名を含まない)|
|setProjection|String|取得するオブジェクトのメタデータ<br><br>"full"(全てのメタデータ)、"noAcl"(ACLを含まないメタデータ)|
|setSoftDeleted|Boolean|論理的に削除されたオブジェクトのバージョンのみを取得するか|
|setVersions|Boolean|オブジェクトの全てのバージョンを取得するか|

#### globパターン
|globパターン|説明|
|---|---|
|?|任意の1文字がオブジェクト名にマッチ|	
|*|任意の1文字、もしくは文字なしがオブジェクト名にマッチ|	
|**|指定したディレクトリの配下階層を再起的に検索|	
|**\/|指定したディレクトリの階層までを検索|
|[abc]|括弧内のどれか1文字がオブジェクト名にマッチ|	
|[a-z]|括弧内の範囲のどれか1文字がオブジェクト名にマッチ|
|[!abc]|括弧内のどれか1文字がオブジェクト名にマッチしない|
|{abc,xyz}|abc、xyzのいずれかにオブジェクト名がマッチ|	
|{foo,{a,b}{x,y},bar}|foo、ax、ay、bx、 byのいずれかにオブジェクト名がマッチ|	
|{foo*,*bar}|foo接頭辞のオブジェクト名、またはbar接尾辞のオブジェクト名のいずれかにオブジェクト名がマッチ|
|\\?|特殊文字のエスケープ<br>次の文字は特殊文字<br>「?」、「*」、「\\」、「[」、「]」、「{」、「}」|

### 1.3. レスポンスの内容
#### Objects
|メソッド|戻り値|説明|
|---|---|---|
|getKind|String|リソースの種類<br>固定文字列："storage#objects"|
|getNextPageToken|String|次のページトークン|
|getItems|List\<[StorageObject](#storageobject)\>|オブジェクトのリスト|
|getPrefixes|List\<String\>|getItems()で取得できるオブジェクトから除外されたプレフィックス名。<br><br>例えば、setDelimiter("/")のみ(フォルダ区切り)を指定した場合、getItems()に直下階層のオブジェクト、getPrefixes()には直下階層のフォルダのプレフィックス名が取得できる。|

#### StorageObject
|メソッド|戻り値|説明|
|---|---|---|
|getId|String|オブジェクトID|	
|getKind|String|リソースの種類<br>固定文字列："storage#object"| 
|getName|String|オブジェクトの名前|
|getBucket|String|バケット名|
|getSize|BigInteger|データサイズ(バイト単位)|
|getGeneration|Long|世代番号(generation)|
|getMetageneration|Long|メタ世代番号(metageneration)|
|getEtag|String|オブジェクトのHTTPエンティティタグ|
|getMediaLink|String|オブジェクトのデータをダウンロードするためのURL|
|getSelfLink|String|オブジェクトのURL|
|getAcl|List\<[ObjectAccessControl](#objectaccesscontrol)|オブジェクトのアクセスコントロール |
|getCacheControl|String|オブジェクトデータのCache-Controlディレクティブ|
|getComponentCount|Integer|複合オブジェクトの場合の非複合オブジェクトの数|
|getContentDisposition|String|Contentオブジェクトデータの配置|
|getContentEncoding|String|Contentオブジェクトデータのエンコーディング|
|getContentLanguage|String|Contentオブジェクトデータの言語|
|getContentType|String|ContentオブジェクトデータのContent-Type|
|getCustomerEncryption|[StorageObject.CustomerEncryption](#storageobjectcustomerencryption)|顧客が指定した暗号化キーのメタデータ|	
|getEventBasedHold|Boolean|オブジェクトがイベントベースの保留の対象か|
|getKmsKeyName|String|このオブジェクトの暗号化に使用されるCloudKMS鍵|
|getMd5Hash|String|データのMD5ハッシュ値|
|getMetadata|Map\<String,String\>|ユーザーが提供するメタデータ|
|getOwner|[StorageObject.Owner](#storageobjectowner)|オブジェクトの所有者|
|getRetention|[StorageObject.Retention](#storageobjectretention)|オブジェクトの保持設定|
|getRetentionExpirationTime|DateTime|オブジェクトが削除可能なる最も早い時間|
|getSoftDeleteTime|DateTime|オブジェクトが論理的に削除された時刻|	
|getHardDeleteTime|DateTime|論理的に削除されたオブジェクトが完全に削除された時刻|
|getStorageClass|String|オブジェクトのストレージクラス|
|getTemporaryHold|Boolean|オブジェクトが 一時保留の対象か|
|getTimeCreated|DateTime|オブジェクトの作成時刻|
|getTimeDeleted|DateTime|オブジェクトの削除時刻|
|getTimeStorageClassUpdated|DateTime|オブジェクトのストレージクラスが最後に変更された時刻|
|getCustomTime|DateTime|ユーザー指定のタイムスタンプ|
|getUpdated|DateTime|オブジェクトのメタデータ変更時刻|

#### ObjectAccessControl
|メソッド|戻り値|説明|
|---|---|---|
|getKind|String|リソースの種類<br>固定文字列："storage#objectAccessControl"| 
|getDomain|String|エンティティに関連付けられているドメイン|
|getEmail|String|エンティティに関連付けられているメールアドレス|
|getEntity|String|権限を保持するエンティティ<br><br>次のいずれかの形式<br>user-{email}<br>group-{groupId}<br>group-{email}<br>domain-{domain}<br>project-{team-projectId}<br>allUsers<br>allAuthenticatedUsers|
|getEntityId|String|エンティティID|
|getEtag|String|アクセス制御エントリのHTTPエンティティタグ|
|getProjectTeam|[ObjectAccessControl.ProjectTeam](#objectaccesscontrolprojectteam)|エンティティに関連付けられているプロジェクトチーム|
|getRole|String|エンティティのアクセス許可<br>"OWNER"、"READER"、"WRITER"|

#### ObjectAccessControl.ProjectTeam
|メソッド|戻り値|説明|
|---|---|---|
|getProjectNumber|String|プロジェクト番号| 
|getTeam|String|チーム役割<br>"editors"、"owners"、"viewers"|

#### StorageObject.CustomerEncryption
|メソッド|戻り値|説明|
|---|---|---|
|getEncryptionAlgorithm|String|暗号化アルゴリズム|
|getKeySha256|String|暗号化キーの SHA256 ハッシュ値|

#### StorageObject.Owner
|メソッド|戻り値|説明|
|---|---|---|
|getEntity|String|エンティティ|
|getEntityId|String|エンティティID|

#### StorageObject.Retention
|メソッド|戻り値|説明|
|---|---|---|
|getMode|String|保持設定のモード<br>"Unlocked"(変更可)、"Locked"(変更不可)|
|getRetainUntilTime|DateTime|オブジェクトを削除または置換が可能になった時刻|

### 1.4. オブジェクト一覧のパラメータの指定例
フォルダ構成を下記とします。
```
.
├─ /Folder1
|   ├─/Folder1_sub1
|   |    └─File1_sub1
|   ├─/Folder1_sub2
|   |    └─File1_sub2
|   └─File1
├─ /Folder2
│    └─ /Folder2_sub1
└─ File
```

### 1.4.1. 全てのオブジェクトを取得
パラメータの指定：なし
結果：
|取得メソッド|オブジェクト|
|---|---|
|getPrefixes|なし|
|getItems|File<br>Folder1/<br>Folder1/File1<br>Folder1/Folder1_sub1/<br>Folder1/Folder1_sub1/File1_sub1<br>Folder1/Folder1_sub2/<br>Folder1/Folder1_sub2/File1_sub2<br>Folder2/<br>Folder2/Folder2_sub1/|

アイテムに全てのオブジェクトとフォルダが取得できます。

### 1.4.2. ルート階層配下のみを取得
パラメータの指定：
```java
　setDelimiter("/");
```
結果：
|取得メソッド|オブジェクト|
|---|---|
|getPrefixes|Folder1/<br>Folder2/|
|getItems|File|

プレフィックスにルート直下のフォルダ、
アイテムにルート直下のオブジェクト
が取得できます。

プレフィックスのアイテムも取得したい場合は、
setIncludeTrailingDelimiter(true)を指定します。

### 1.4.3. 指定フォルダ配下のみ取得
パラメータの指定：
```java
setDelimiter("/");
setPrefix("Folder1/");
```
結果：
|取得メソッド|オブジェクト|
|---|---|
|getPrefixes|Folder1/Folder1_sub1/<br>Folder1/Folder1_sub2/|
|getItems|Folder1/<br>Folder1/File1|

プレフィックスに指定フォルダ直下のフォルダ、
アイテムに指定フォルダ直下のオブジェクト(自身のフォルダ含む)
が取得できます。

プレフィックスのアイテムも取得したい場合は、
setIncludeTrailingDelimiter(true)を指定します。

## 2. オブジェクトを取得
指定したオブジェクトのメタデータを取得します。

### 2.1. スコープ
このAPIを実行するには、以下のいずれかのスコープを指定してください。
```
StorageScopes.CLOUD_PLATFORM
StorageScopes.CLOUD_PLATFORM_READ_ONLY
StorageScopes.DEVSTORAGE_FULL_CONTROL
StorageScopes.DEVSTORAGE_READ_ONLY
StorageScopes.DEVSTORAGE_READ_WRITE
```
[⧉[Cloud Storage API(V2)] JavaでCloud Storageを使う(2.2 Storageインスタンスを取得)](https://qiita.com/doran/items/2a5f7ef8070fd5b8c94d#22-storageインスタンスを取得)
でスコープを指定してください。

### 2.2. 実行
オブジェクト名は、[StorageObject](#storageobject)のgetName()で取得できる値を使用します。

```java
public static void main(String[] args) throws Exception{
    Storage storage = getStorage();
    Storage.Objects objects = storage.objects();
    
    Storage.Objects.Get get = objects.get("バケットID","オブジェクト名");
    
    StorageObject res = get.execute();
    System.out.println(res);
}
```
#### 2.2.1. HTTPリクエスト
GET:　https:\//storage.googleapis.com/storage/v1/b/{バケットID}/o/{オブジェクト名}
が実行されます。

#### 2.2.2. クエリパラメータ
Storage.Buckets.Getのsetメソッドにより、クエリパラメータを追加できます。

|メソッド|引数|説明|
|---|---|---|
|setAlt|String|取得するデータのタイプ|返されるデータのタイプ<br><br>"json"(オブジェクトのメタデータ)、"media"(オブジェクトデータ)|
|setIfGenerationMatch|Long|世代番号(generation)と一致する場合のみオブジェクトを取得|
|setIfGenerationNotMatch|Long|世代番号(generation)と一致しない場合のみオブジェクトを取得|
|setIfMetagenerationMatch|Long|メタ世代番号(metageneration)と一致した場合のみオブジェクトを取得|
|setIfMetagenerationNotMatch|Long|メタ世代番号(metageneration)と一致しない場合のみオブジェクトを取得|
|setProjection|String|取得するメタデータ<br><br>"full"(全てのメタデータ)、"noAcl"(ACL情報を除くメタデータ)|
|setSoftDeleted|Boolean|論理的に削除されたオブジェクトを取得するか|
|setGeneration|Long|【setSoftDeleted(true)の場合は必須】<br>世代番号(generation)|

### 2.3. レスポンスの内容
#### StorageObject
[2.3. レスポンスの内容(StorageObject)](#storageobject)と同じです。
<br>
<br>
おしまい。。