[Google Cloud Speech-to-Text API(V2)] Javaで認識精度を向上させるカスタムクラスを作成・更新・削除する

Cloud Speech-to-Text API V2(Java)を使用して、
認識精度を向上させるカスタムクラスを作成・更新・削除する方法についてご紹介します。

**カスタムクラス(CustomClass)とは**
カスタムクラス(CustomClass)はモデル適応機能を実現させるためのリソースの1つです。

モデル適応機能を使用すると提案される可能性がある他の候補よりも、
Speech-to-Textが特定の単語やフレーズをより高い頻度で認識するように設定できます。

カスタムクラス(CustomClass)リソースでは下記が設定できます。
|できること|概要|
|---|---|
|固有名称(店名や商品名など)の認識|カスタムクラスを使用すると、音声に出現した際に固有名称を正しく認識するように認識モデルにバイアスをかけることができます。|

:::note info
APIを利用する環境の準備から始める場合や、コードを実行する際は、
[⧉[Google Cloud Speech-to-Text API(V2)] JavaでSpeech-to-Text APIを使ってみる](https://qiita.com/doran/items/8e4ef896588229c4fed3)
を参照ください。
:::

|No||目次|
|---|---|---|
|1||[カスタムクラスを作成](#1-カスタムクラスを作成)|
||1|[スコープ](#11-スコープ)|
||2|[実行](#12-実行)|
||3|[レスポンスの内容](#13-レスポンスの内容)|
|2||[カスタムクラスを更新](#2-カスタムクラスを更新)|
||1|[スコープ](#21-スコープ)|
||2|[実行](#22-実行)|
||3|[レスポンスの内容](#23-レスポンスの内容)|
|3||[カスタムクラスを削除](#3-カスタムクラスを削除)|
||1|[スコープ](#31-スコープ)|
||2|[実行](#32-実行)|
||3|[レスポンスの内容](#33-レスポンスの内容)|

## 1. カスタムクラスを作成
カスタムクラスを作成します。

### 1.1. スコープ
OAuth2.0でこのAPIを実行するには、以下のスコープを指定してください。
サービスアカウントで実行する場合はスコープの指定は不要です。
```
https://www.googleapis.com/auth/cloud-platform
```

### 1.2. 実行
カスタムクラスIDには、これから作成するカスタムクラスのIDを設定します。
既に存在するIDを指定した場合はエラーになります。

```java
public static void main(String[] args) throws Exception{
    try(SpeechClient client = getSpeechClient()){
        ClassItem.Builder item = ClassItem.newBuilder();
        item.setValue("ポムポムプリン");
        
        CustomClass.Builder custom = CustomClass.newBuilder();
        custom.addItems(item.build());
        
        CreateCustomClassRequest.Builder builder = CreateCustomClassRequest.newBuilder();
        builder.setParent(String.format(
                        "projects/%s/locations/%s", 
                        "プロジェクトID","ロケーションID"));
        builder.setCustomClass(custom.build());
        builder.setCustomClassId("カスタムクラスID");
        
        OperationFuture<CustomClass,OperationMetadata> response = client.createCustomClassAsync(builder.build());
        System.out.println(response.getName());
        
        CustomClass get = response.get();
        System.out.println(get);
    }
}
```

#### 1.2.1. HTTPリクエスト
POST:　https:\//speech.googleapis.com/v2/projects/{プロジェクトID}/locations/{ロケーションID}/customClasses
が実行されます。

#### 1.2.2. クエリパラメータ
CreateCustomClassRequest.Builderのsetメソッドにより、リクエストボディを追加できます。
build()メソッドでCreateCustomClassRequestインスタンスを取得し、
createCustomClassAsync()に渡します。

|メソッド|引数|説明|
|---|---|---|
|setParent|String|【必須】リソース名<br>形式："projects/{プロジェクトID}/locations/{ロケーションID}"|
|setCustomClassId|String|【必須】カスタムクラスID|
|setCustomClass|[CustomClass](#customclassset)|【必須】カスタムクラス|
|setValidateOnly|boolean|リクエストを検証してカスタムクラスをプレビューするが実際には作成しないか|

#### 1.2.3. リクエストボディ
#### CustomClass(Set)
|メソッド|引数|説明|
|---|---|---|
|setName|String|【更新時のみ必須】リソース名<br>形式："projects/{プロジェクトID}/locations/{ロケーションID}/customClasses/{カスタムクラスID}"|
|setDisplayName|String|カスタムクラスの名前(63文字まで)|
|addItemsList|[ClassItem](#classitemset)|カスタムクラス|

#### ClassItem(Set)
|メソッド|引数|説明|
|---|---|---|
|setValue|String|クラス項目の値|

### 1.3. レスポンスの内容
#### OperationFuture\<CustomClass,OperationMetadata\>
|メソッド|戻り値|説明|
|---|---|---|
|getName|String|サーバーによって割り当てられた名前<br>形式："projects/{プロジェクトID}/locations/{ロケーションID}/customClasses/{カスタムクラスID}"|
|isDone|boolean|操作がまだ進行中であるか|
|getPollingFuture|RetryingFuture\<[OperationSnapshot](#operationsnapshot)\>|失敗またはキャンセルされた場合の操作のエラー結果|
|get|[CustomClass](#customclass)|カスタムクラスデータ|

#### CustomClass
|メソッド|戻り値|説明|
|---|---|---|
|getName|String|カスタムクラスのリソース名<br>形式："projects/{プロジェクトID}/locations/{ロケーションID}/customClasses/{カスタムクラスID}"|
|getUid|String|システムによって割り当てられたカスタムクラスID|
|getDisplayName|String|カスタムクラスの名前(63文字まで)|
|getItemsList|List\<[ClassItem](#classitem)\>|カスタムクラスのリスト|
|getState|[State(enum)](#state)|カスタムクラスのライフサイクル状態|
|getCreateTime|Timestamp|カスタムクラスの作成時間|
|getUpdateTime|Timestamp|カスタムクラスが最後に変更された時刻|
|getDeleteTime|Timestamp|カスタムクラスの削除が要求された時刻|
|getExpireTime|Timestamp|カスタムクラスがパージされる時刻|
|getEtag|String|チェックサム値|
|getReconciling|boolean|カスタムクラスが更新中か|
|getKmsKeyName|String|カスタムクラスの暗号化に使用されるKMSキーの名前<br>形式："projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}"|
|getKmsKeyVersionName|String|カスタムクラスの暗号化に使用されるKMSキーのバージョン名<br>形式："projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}"|

#### ClassItem
|メソッド|戻り値|説明|
|---|---|---|
|getValue|String|クラス項目の値|

#### OperationSnapshot
|メソッド|戻り値|説明|
|---|---|---|
|getErrorCode|StatusCode|エラーコード|
|getErrorMessage|String|開発者向けのエラーメッセージ|

#### State
|定義値|内容|
|---|---|
|STATE_UNSPECIFIED|未指定|
|ACTIVE|通常のアクティブな状態|
|DELETED|カスタムクラスは削除された|

## 2. カスタムクラスを更新
指定したカスタムクラスを更新します。

### 2.1. スコープ
OAuth2.0でこのAPIを実行するには、以下のスコープを指定してください。
サービスアカウントで実行する場合はスコープの指定は不要です。
```
https://www.googleapis.com/auth/cloud-platform
```

### 2.2. 実行

```java
public static void main(String[] args) throws Exception{
    try(SpeechClient client = getSpeechClient()){
		ClassItem.Builder item = ClassItem.newBuilder();
		item.setValue("シナモロール");
        
        CustomClass.Builder custom = CustomClass.newBuilder();
        custom.setName(String.format(
                        "projects/%s/locations/%s/customClasses/%s", 
                        "プロジェクトID","ロケーションID","カスタムクラスID"));
        custom.addItems(item.build());
        
        UpdateCustomClassRequest.Builder builder = UpdateCustomClassRequest.newBuilder();
        builder.setCustomClass(custom.build());
        
        OperationFuture<CustomClass,OperationMetadata> response = client.updateCustomClassAsync(builder.build());
        System.out.println(response.getName());
        
        CustomClass get = response.get();
        System.out.println(get);
    }
}
```

#### 2.2.1. HTTPリクエスト
PATCH:　https:\//speech.googleapis.com/v2/projects/{プロジェクトID}/locations/{ロケーションID}/customClasses/{カスタムクラスID}
が実行されます。

#### 2.2.2. クエリパラメータ
UpdateCustomClassRequest.Builderのsetメソッドにより、リクエストボディを追加できます。
build()メソッドでUpdateCustomClassRequestインスタンスを取得し、
updateCustomClassAsync()に渡します。

|メソッド|引数|説明|
|---|---|---|
|setCustomClass|[CustomClass](#customclassset)|【必須】カスタムクラス|
|setUpdateMask|FieldMask|更新するフィールド<br>未設定の場合は全てのフィールドが更新対象|
|setValidateOnly|boolean|リクエストを検証し、更新されたカスタムクラスをプレビューするが実際には更新しないか|

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

### 2.3. レスポンスの内容
#### OperationFuture\<CustomClass,OperationMetadata\>

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

## 3. カスタムクラスを削除
指定したカスタムクラスを削除します。

### 3.1. スコープ
OAuth2.0でこのAPIを実行するには、以下のスコープを指定してください。
サービスアカウントで実行する場合はスコープの指定は不要です。
```
https://www.googleapis.com/auth/cloud-platform
```

### 3.2. 実行

```java
public static void main(String[] args) throws Exception{
    try(SpeechClient client = getSpeechClient()){
        DeleteCustomClassRequest.Builder builder = DeleteCustomClassRequest.newBuilder();
        builder.setName(String.format(
                    "projects/%s/locations/%s/customClasses/%s", 
                    "プロジェクトID","ロケーションID","カスタムクラスID"));
        
        OperationFuture<CustomClass,OperationMetadata> response = client.deleteCustomClassAsync(builder.build());
        System.out.println(response.getName());
        
        CustomClass get = response.get();
        System.out.println(get);
    }
}
```

#### 3.2.1. HTTPリクエスト
DELETE:　https:\//speech.googleapis.com/v2/projects/{プロジェクトID}/locations/{ロケーションID}/customClasses/{カスタムクラスID}
が実行されます。

#### 3.2.2. クエリパラメータ
DeleteCustomClassRequest.Builderのsetメソッドにより、クエリパラメータを追加できます。
build()メソッドでDeleteCustomClassRequestインスタンスを取得し、
deleteCustomClassAsync()に渡します。

|メソッド|引数|説明|
|---|---|---|
|setValidateOnly|boolean|リクエストを検証し、削除されたカスタムクラスをプレビューするが実際には削除しないか|
|setAllowMissing|boolean|カスタムクラスが見つからない場合、リクエストは成功し操作は行わないか|
|setEtag|String|チェックサム値|

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

### 3.3. レスポンスの内容
#### OperationFuture\<CustomClass,OperationMetadata\>

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