[Cloud Storage API(V2)] Javaでオブジェクトのアクセス制御リスト(ACL)エントリを作成・更新・削除する

Cloud Storage API V2(Java)を使用して、
Cloud Storageオブジェクトのアクセス制御リスト(ACL)エントリを作成・更新・削除する方法
についてご紹介します。

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

|No|||目次|
|---|---|---|---|
|1|||[ACLを作成](#1-aclを作成)|
||1||[スコープ](#11-スコープ)|
||2||[実行](#12-実行)|
||3||[レスポンスの内容](#13-レスポンスの内容)|
|2|||[ACLを上書き](#2-aclを上書き)|
||1||[スコープ](#21-スコープ)|
||2||[実行](#22-実行)|
||3||[レスポンスの内容](#13-レスポンスの内容)|
|3|||[ACLを更新](#3-aclを更新)|
||1||[スコープ](#31-スコープ)|
||2||[実行](#32-実行)|
||3||[レスポンスの内容](#33-レスポンスの内容)|
|4|||[ACLを削除](#4-aclを削除)|
||1||[スコープ](#41-スコープ)|
||2||[実行](#42-実行)|
||3||[レスポンスの内容](#43-レスポンスの内容)|

## 1. ACLを作成
指定したオブジェクトにACLエントリを作成します。

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

### 1.2. 実行
オブジェクト名は、[⧉ StorageObjectのgetName()](https://qiita.com/doran/items/41f683394d80ea80ba84#storageobject)で取得できる値を使用します。

gsutil URIでオブジェクト名の位置を示すと
```
gs://{バケットID}/{オブジェクト名}
```
の部分になります。


```java
public static void main(String[] args) throws Exception{
    BucketAccessControl res = insert.execute();
    System.out.println(res);
    
    Storage storage = getStorage();
    Storage.ObjectAccessControls access = storage.objectAccessControls();
    
    ObjectAccessControl content = new ObjectAccessControl();
    content.setEntity("エンティティ");
    content.setRole("アクセス許可");
    Storage.ObjectAccessControls.Insert insert = access.insert("バケットID","オブジェクト名",content);
    
    ObjectAccessControl res = insert.execute();
    System.out.println(res);
}
```
#### 1.2.1. HTTPリクエスト
POST:　https:\//storage.googleapis.com/storage/v1/b/{バケットID}/o/{オブジェクト名}/acl
が実行されます。

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

|メソッド|引数|説明|
|---|---|---|
|setGeneration|Long|世代番号(generation)|

#### 1.2.3. リクエストボディ
ObjectAccessControlのsetメソッドにより、リクエストボディを追加できます。

|メソッド|引数|説明|
|---|---|---|
|setEntity|String|【作成時のみ必須】<br>権限を保持するエンティティ<br><br>次のいずれかの形式<br>user-{email}<br>group-{groupId}<br>group-{email}<br>domain-{domain}<br>project-{team-projectId}<br>allUsers<br>allAuthenticatedUsers|
|setRole|String|【作成時のみ必須】<br>エンティティのアクセス許可<br><br>"OWNER"、"READER"|

### 1.3. レスポンスの内容
#### ObjectAccessControl
|メソッド|戻り値|説明|
|---|---|---|
|getId|String|アクセス制御エントリID|
|getObject|String|オブジェクト名|
|getKind|String|リソースの種類<br>固定文字列："storage#objectAccessControl"|
|getGeneration|Long|世代番号(generation)|
|getBucket|String|バケットの名前|
|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"|
|getSelfLink|String|アクセス制御エントリへのリンク|

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

## 2. ACLを上書き
指定したオブジェクトのACLエントリを上書きします。

[3. ACLを更新](#3-aclを更新)と違うところは、
指定した存在するACLエントリを新しいACLエントリに置き換えます。

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

### 2.2. 実行

```java
public static void main(String[] args) throws Exception{
    Storage storage = getStorage();
    Storage.ObjectAccessControls access = storage.objectAccessControls();
    
    ObjectAccessControl content = new ObjectAccessControl();
    content.setRole("アクセス許可");
    Storage.ObjectAccessControls.Update update = access.update("バケットID","オブジェクト名","エンティティ",content);
    
    ObjectAccessControl res = update.execute();
    System.out.println(res);
}
```
#### 2.2.1. HTTPリクエスト
PUT:　https:\//storage.googleapis.com/storage/v1/b/{バケットID}/o/{オブジェクト名}/acl/{エンティティ}
が実行されます。

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

|メソッド|引数|説明|
|---|---|---|
|setGeneration|Long|世代番号(generation)|

#### 2.2.3. リクエストボディ
ObjectAccessControlのsetメソッドにより、リクエストボディを追加できます。

[1.2.3. リクエストボディ](#123-リクエストボディ)と同じです。

### 2.3. レスポンスの内容
#### ObjectAccessControl
[1.3. レスポンスの内容(ObjectAccessControl)](#objectaccesscontrol)と同じです。

## 3. ACLを更新
指定したオブジェクトのACLエントリを更新します。

[2. ACLを上書き](#2-aclを上書き)と違うところは、
指定したオブジェクトのACLエントリのみを更新します。

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

### 3.2. 実行

```java
public static void main(String[] args) throws Exception{
    Storage storage = getStorage();
    Storage.ObjectAccessControls access = storage.objectAccessControls();
    
    ObjectAccessControl content = new ObjectAccessControl();
    //更新内容を設定
    
    Storage.ObjectAccessControls.Patch patch = access.patch("バケットID","オブジェクト名","エンティティ",content);
    
    ObjectAccessControl res = patch.execute();
    System.out.println(res);
}
```
#### 3.2.1. HTTPリクエスト
PATCH:　https:\//storage.googleapis.com/storage/v1/b/{バケットID}/o/{オブジェクト名}/acl/{エンティティ}
が実行されます。

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

|メソッド|引数|説明|
|---|---|---|
|setGeneration|Long|世代番号(generation)|

#### 3.2.3. リクエストボディ
ObjectAccessControlのsetメソッドにより、リクエストボディを追加できます。

[1.2.3. リクエストボディ](#123-リクエストボディ)と同じです。

### 3.3. レスポンスの内容
#### ObjectAccessControl
[1.3. レスポンスの内容(ObjectAccessControl)](#objectaccesscontrol)と同じです。

## 4. ACLを削除
指定したオブジェクトのACLエントリを削除します。

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

### 4.2. 実行

```java
public static void main(String[] args) throws Exception{
    Storage storage = getStorage();
    Storage.ObjectAccessControls access = storage.objectAccessControls();
    
    Storage.ObjectAccessControls.Delete delete = access.delete("バケットID","オブジェクト名","エンティティ");
    
    delete.execute();
}
```
#### 4.2.1. HTTPリクエスト
DELETE:　https:\//storage.googleapis.com/storage/v1/b/{バケットID}/o/{オブジェクト名}/acl/{エンティティ}
が実行されます。

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

#### 4.2.3. リクエストボディ
リクエストボディはありません。

### 4.3. レスポンスの内容
レスポンスはありません。
削除に失敗した場合は例外が発生します。

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