[Google Cloud Speech-to-Text API(V2)] Javaで認識ツールを作成・更新・削除する

Cloud Speech-to-Text API V2(Java)を使用して、
認識ツールを作成・更新・削除する方法についてご紹介します。

**認識ツールとは**
認識ツールは構成可能で再利用可能な認識構成です。

頻繁に使用される認識構成を使用して認識ツールを作成すると、
認識リクエストを簡素化し、リクエストのサイズを削減できます。

:::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. 実行

```java
public static void main(String[] args) throws Exception{
		try(SpeechClient client = getSpeechClient()){
			RecognitionConfig.Builder config = RecognitionConfig.newBuilder();
			config.setModel("short");
			config.addLanguageCodes("ja-JP");
			
			Recognizer.Builder value = Recognizer.newBuilder();
			value.setDefaultRecognitionConfig(config.build());
			
			CreateRecognizerRequest.Builder builder = CreateRecognizerRequest.newBuilder();
			builder.setParent(String.format(
                       "projects/%s/locations/%s", 
                       "プロジェクトID","ロケーションID"));
			builder.setRecognizerId("認証ツールID");
			builder.setRecognizer(value.build());
			
			OperationFuture<Recognizer,OperationMetadata> response = client.createRecognizerAsync(builder.build());
	        System.out.println(response.getName());

	        Recognizer get = response.get();
	        System.out.println(get);
		}
}
```
#### 1.2.1. HTTPリクエスト
POST:　https:\//speech.googleapis.com/v2/projects/{プロジェクトID}/locations/{ロケーションID}/recognizers
が実行されます。

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

|メソッド|引数|説明|
|---|---|---|
|setParent|String|【必須】リソース名<br>形式："projects/{プロジェクトID}/locations/{ロケーションID}"|
|setRecognizerId|String|【必須】認証ツールID|
|setRecognizer|[Recognizer](#recognizer)|【必須】認識ツールの情報|
|setValidateOnly|boolean|リクエストを検証して認証ツールをプレビューするが実際には作成しないか|

#### 1.2.3. リクエストボディ
#### Recognizer
|メソッド|引数|説明|
|---|---|---|
|setDisplayName|String|認証ツールの名前(63文字まで)|
|setDefaultRecognitionConfig|[RecognitionConfig](#recognitionconfig)|リクエストに使用するデフォルトの構成|

#### RecognitionConfig
|メソッド|引数|説明|
|---|---|---|
|setModel|String|【作成時のみ必須】モデル<br><br>[⧉Speech-to-TextV2でのサポート言語](https://cloud.google.com/speech-to-text/v2/docs/speech-to-text-supported-languages?hl=ja)の「モデル」を指定|
|addLanguageCodesList|String|【作成時のみ必須】変換する言語<br><br>[⧉Speech-to-TextV2でのサポート言語](https://cloud.google.com/speech-to-text/v2/docs/speech-to-text-supported-languages?hl=ja)の「BCP-47」を指定|
|setFeatures|[RecognitionFeatures](#recognitionfeatures)|有効にする音声認識機能|
|setAdaptation|[SpeechAdaptation](#speechadaptation)|特定の単語やフレーズに対する認識エンジンの予測を重み付けする音声適応コンテキスト|
|setTranscriptNormalization|[TranscriptNormalization](#transcriptnormalization)|文字起こしの正規化を使用して文字起こしの一部を選択したフレーズに自動的に置き換えるユニオンフィールド|
|setAutoDecodingConfig|[AutoDetectDecodingConfig(enum)](#autodetectdecodingconfig)|デコードパラメータを自動的に検出<br>explicitDecodingConfigの設定がない場合は必須(空のインスタンスを設定)|
|setExplicitDecodingConfig|[ExplicitDecodingConfig](#explicitdecodingconfig)|明示的に指定されたデコードパラメータ<br>ヘッダーレスPCMオーディオ(linear16、mulaw、alaw)の場合は必須|

#### RecognitionFeatures
|メソッド|引数|説明|
|---|---|---|
|setProfanityFilter|boolean|フィルタリングされた各単語の最初の文字を除くすべての文字をアスタリスクに置き換えるか|
|setEnableWordTimeOffsets|boolean|一番上の結果には単語のリストと、それらの単語の開始時刻と終了時刻のオフセット(タイムスタンプ)が含まれるか|
|setEnableWordConfidence|boolean|一番上の結果には単語のリストとそれらの単語の信頼度が含まれるか|
|setEnableAutomaticPunctuation|boolean|認識結果の仮説に句読点を追加するか|
|setEnableSpokenPunctuation|boolean|音声の句読点をリクエスト内の対応する記号に置き換えるか|
|setEnableSpokenEmojis|boolean|リクエストに音声絵文字の書式設定を追加するか|
|setMultiChannelMode|[MultiChannelMode(enum)](#multichannelmode)|マルチチャンネルオーディオを認識するモード|
|setDiarizationConfig|[SpeakerDiarizationConfig](#speakerdiarizationconfig)|追加パラメータを設定するための構成|
|setMaxAlternatives|int|返される認識仮説の最大数(0〜30)|

#### SpeakerDiarizationConfig
|メソッド|引数|説明|
|---|---|---|
|setMinSpeakerCount|int|会話内の発言者の最小数(1〜6)|
|setMaxSpeakerCount|int|会話内の発言者の最大数(1〜6)|

#### SpeechAdaptation
|メソッド|引数|説明|
|---|---|---|
|addPhraseSetsList|[AdaptationPhraseSet](#adaptationphraseset)|インラインフレーズセットのリスト|
|addCustomClassesList|[⧉ CustomClass](https://qiita.com/doran/items/ac0218b030725bff90f1#customclassset)|インラインカスタムクラスのリスト|

#### AdaptationPhraseSet
|メソッド|引数|説明|
|---|---|---|
|setPhraseSet|String|既存のフレーズセットの名前|
|setInlinePhraseSet|[⧉ PhraseSet](https://qiita.com/doran/items/3c500c5b05153e295146#phrasesetset)|インラインで定義されたフレーズセット|

#### ExplicitDecodingConfig
|メソッド|引数|説明|
|---|---|---|
|setEncoding|[AudioEncoding(enum)](#audioencoding)|認識のために送信される音声データのエンコーディング|
|setSampleRateHertz|int|認識のために送信されるオーディオデータのサンプルレート(ヘルツ)(8000～48000)<br>[サポートエンコーディング](#サポートエンコーディング)|
|audioChannelCount|int|認識のために送信された音声データに存在するチャネルの数(最大8)<br>[サポートエンコーディング](#サポートエンコーディング)|

#### TranscriptNormalization
|メソッド|引数|説明|
|---|---|---|
|addEntriesList|[TranscriptNormalization.Entry](#transcriptnormalizationentry)|置換エントリのリスト(最大100)|

#### TranscriptNormalization.Entry
|メソッド|引数|説明|
|---|---|---|
|setSearch|String|何を交換するか(最大100文字)|
|setReplace|String|何と交換するか(最大100文字)|
|setCaseSensitive|boolean|検索で大文字と小文字が区別されるか|

#### AutoDetectDecodingConfig
|定義値|内容|
|---|---|
|WAV_LINEAR16|WAVコンテナー内の16ビット符号付きリトルエンディアンPCMサンプル|
|WAV_MULAW|WAVコンテナ内の8ビット圧縮されたmulawサンプル|
|WAV_ALAW|WAVコンテナ内の8ビット圧縮されたalawサンプル|
|RFC4867_5_AMR|rfc4867.5ヘッダーを持つAMRフレーム|
|RFC4867_5_AMRWB|rfc4867.5ヘッダーを持つAMR-WBフレーム|
|FLAC|「ネイティブFLAC」コンテナ形式のFLACフレーム|
|MP3|オプションの(無視される)ID3メタデータを含むMPEGオーディオフレーム|
|OGG_OPUS|Oggコンテナ内のOpusオーディオフレーム|
|WEBM_OPUS|WebMコンテナ内のOpusオーディオフレーム|
|M4A|M4Aオーディオ形式|

#### MultiChannelMode
|定義値|内容|
|---|---|
|MULTI_CHANNEL_MODE_UNSPECIFIED|マルチチャンネルモードのデフォルト値|
|SEPARATE_RECOGNITION_PER_CHANNEL|提供されたオーディオの各チャネルが個別に転写される|

#### AudioEncoding
|定義値|内容|
|---|---|
|AUDIO_ENCODING_UNSPECIFIED|デフォルト値|
|LINEAR16|ヘッダーなしの16ビット符号付きリトルエンディアンPCMサンプル|
|MULAW|ヘッダーなしの8ビット圧縮されたmulawサンプル|
|ALAW|ヘッダーなしの8ビット圧縮されたalawサンプル|

#### サポートエンコーディング
|定義値|内容|
|---|---|
|LINEAR16|ヘッダーなしの16ビット符号付きリトルエンディアンPCMサンプル|
|MULAW|ヘッダーのない8ビットの圧縮されたmulawサンプル|
|ALAW|ヘッダーなしの8ビット圧縮されたalawサンプル|

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

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

## 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()){
        Recognizer.Builder recognizer = Recognizer.newBuilder();
        recognizer.setName(String.format(
                    "projects/%s/locations/%s/recognizers/%s", 
                    "プロジェクトID","ロケーションID","認証ツールID"));
        
        UpdateRecognizerRequest.Builder builder = UpdateRecognizerRequest.newBuilder();
        builder.setRecognizer(recognizer.build());
        
        OperationFuture<Recognizer,OperationMetadata> response = client.updateRecognizerAsync(builder.build());
        System.out.println(response.getName());

        Recognizer get = response.get();
        System.out.println(get);
    }
}
```
#### 2.2.1. HTTPリクエスト
PATCH:　https:\//speech.googleapis.com/v2/projects/{プロジェクトID}/locations/{ロケーションID}/recognizers/{認証ツールID}
が実行されます。

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

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

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

### 2.3. レスポンスの内容
#### OperationFuture\<Recognizer,OperationMetadata\>
[1.3. レスポンスの内容(OperationFuture\<Recognizer,OperationMetadata\>)](#operationfuturerecognizeroperationmetadata)と同じです。

## 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()){
        DeleteRecognizerRequest.Builder builder = DeleteRecognizerRequest.newBuilder();
        builder.setName(String.format(
                    "projects/%s/locations/%s/recognizers/%s", 
                    "プロジェクトID","ロケーションID","認証ツールID"));
        
        OperationFuture<Recognizer,OperationMetadata> response = client.deleteRecognizerAsync(builder.build());
        System.out.println(response.getName());

        Recognizer get = response.get();
        System.out.println(get);
    }
}
```
#### 3.2.1. HTTPリクエスト
DELETE:　https:\//speech.googleapis.com/v2/projects/{プロジェクトID}/locations/{ロケーションID}/recognizers/{認証ツールID}
が実行されます。

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

|メソッド|引数|説明|
|---|---|---|
|setName|String|【必須】リソース名<br>形式："projects/{プロジェクトID}/locations/{ロケーションID}/recognizers/{認証ツールID}"|
|setValidateOnly|boolean|リクエストを検証し、削除された認証ツールをプレビューするが実際には削除しないか|
|setAllowMissing|boolean|認証ツールが見つからない場合、リクエストは成功し操作は行わないか|
|setEtag|String|チェックサム値|

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

### 3.3. レスポンスの内容
#### Recognizer
[⧉ Recognizer](https://qiita.com/doran/items/c952b2f5ea58e8911337#recognizer)と同じです。

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