Package google.assistant.embedded.v1alpha1

索引

EmbeddedAssistant

Google Assistant API を実装するサービス。

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

埋め込みアシスタント サービスとの会話を開始または継続します。呼び出しごとにメッセージが 1 回往復します。すなわち、音声リクエストがサービスに送信され、音声レスポンスが受信されます。双方向ストリーミングを使用して、音声を送信しながら END_OF_UTTERANCE イベントなどの結果を受信します。

会話は 1 つまたは複数の gRPC 接続であり、それぞれの接続が複数のストリーミング リクエストとレスポンスで構成されます。たとえば、ユーザーが「ショッピング リストに追加して」と言うと、アシスタントが「何を追加しますか？」と答えます。最初の gRPC メッセージのストリーミング リクエストとレスポンスの順序は次のとおりです。

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

次に、ユーザーが「ベーグル」と言うと、アシスタントは「わかりました。ベーグルをショッピング リストに追加しました」と答えます。これは、Converse メソッドへの別の gRPC 接続呼び出しとして送信されます。リクエストとレスポンスがストリーミングされます。次に例を示します。

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

レスポンスが正確にこの順序で届くことは保証されませんが、連続した ConverseResponse.audio_out メッセージには常に連続した音声部分が含まれます。

承認

次の OAuth スコープが必要です。

  • https://www.googleapis.com/auth/assistant-sdk-prototype

詳しくは、Auth ガイドをご覧ください。

AudioInConfig

後続のリクエストで提供される audio_in データの処理方法を指定します。推奨設定については、Google Assistant gRPC API のベスト プラクティスをご覧ください。

フィールド
encoding

Encoding

必須。すべての audio_in メッセージで送信される音声データのエンコード。
sample_rate_hertz

int32

必須。すべての audio_in メッセージで送信される音声データのサンプリング レート（ヘルツ単位）。有効な値は 16,000～24,000 ですが、16,000 が最適です。最適な結果を得るには、音源のサンプリング レートを 16,000 Hz に設定します。それができない場合は、（再サンプリングせずに）音源のネイティブ サンプルレートを使用します。

エンコード

音声メッセージで送信されるデータの音声エンコード。音声は 1 チャンネル（モノラル）である必要があります。サポートされている言語は「en-US」のみです。

列挙型
ENCODING_UNSPECIFIED 指定なし。結果 google.rpc.Code.INVALID_ARGUMENT を返します。
LINEAR16 非圧縮 16 ビット符号付きリトル エンディアンのサンプル（Linear PCM）。このエンコードにはヘッダーは含まれず、生の音声バイトのみが含まれます。
FLAC FLAC（Free Lossless Audio Codec）は、ロスレスであり、認識が損なわれないため、LINEAR16 の約半分の帯域幅しか必要としないため、推奨されるエンコードです。このエンコードには FLAC ストリーム ヘッダーが含まれ、その後に音声データが続きます。16 ビットと 24 ビットのサンプルをサポートしていますが、STREAMINFO のすべてのフィールドがサポートされているわけではありません。

AudioOut

クエリに対するアシスタントのレスポンスを含む音声。音声データのシーケンシャル チャンクは、連続した ConverseResponse メッセージで受信されます。

フィールド
audio_data

bytes

出力のみ。クエリに対するアシスタントのレスポンスを含む音声データ。音声データの連続したチャンクは、連続した ConverseResponse メッセージで受信されます。

AudioOutConfig

サーバーが audio_out メッセージを返す際に使用する形式を指定します。

フィールド
encoding

Encoding

必須。すべての audio_out メッセージで返される音声データのエンコード。
sample_rate_hertz

int32

必須。audio_out メッセージで返される音声データのサンプリング レート（ヘルツ単位）。有効な値は 16,000 ～ 24,000 です。

volume_percentage

int32

必須。デバイスの音声出力の現在の音量設定。有効な値は 1 ～ 100（1% ～ 100% に対応）です。

エンコード

音声メッセージで返されるデータの音声エンコード。すべてのエンコードは、下記の例外を除き、ヘッダーのない生の音声バイトです。

列挙型
ENCODING_UNSPECIFIED 指定なし。結果 google.rpc.Code.INVALID_ARGUMENT を返します。
LINEAR16 非圧縮 16 ビット符号付きリトル エンディアンのサンプル（Linear PCM）。
MP3 MP3 音声エンコード。サンプリング レートはペイロードでエンコードされます。
OPUS_IN_OGG ogg コンテナでラップされた Opus エンコード形式の音声。結果は、Android や Chrome などのブラウザでネイティブに再生できるファイルになります。ビットレートが同じ場合、エンコードの品質は MP3 よりもかなり高くなります。サンプリング レートはペイロードでエンコードされます。

ConverseConfig

ConverseRequest メッセージの処理方法を指定します。

フィールド
audio_in_config

AudioInConfig

必須。後続の受信音声の処理方法を指定します。
audio_out_config

AudioOutConfig

必須。返される音声の形式を指定します。
converse_state

ConverseState

必須。現在のダイアログの状態を表します。

ConverseRequest

クライアントから送信される最上位レベル メッセージ。クライアントは、少なくとも 2 つ、通常は多数の ConverseRequest メッセージを送信する必要があります。最初のメッセージには必ず config メッセージが含まれ、audio_in データが含まれることはありません。後続のすべてのメッセージには必ず audio_in データが含まれ、config メッセージが含まれることはありません。

フィールド
共用体フィールド converse_request。各 ConverseRequest で、これらのフィールドのいずれか 1 つのみを指定する必要があります。converse_request は次のいずれかになります。
config

ConverseConfig

config メッセージは、認識機能にリクエストの処理方法を指定する情報を提供します。最初の ConverseRequest メッセージには config メッセージを含める必要があります。
audio_in

bytes

認識する音声データ。音声データの連続したチャンクは、連続した ConverseRequest メッセージで送信されます。最初の ConverseRequest メッセージには audio_in データが含まれることはありません。また、後続のすべての ConverseRequest メッセージには必ず audio_in データが含まれます。音声バイトは AudioInConfig で指定されたとおりにエンコードされる必要があります。音声はほぼリアルタイム（16,000 サンプル/秒）で送信する必要があります。音声の送信速度が大幅に向上または遅い場合は、エラーが返されます。

ConverseResponse

クライアントが受信する最上位レベル メッセージ。一連の ConverseResponse メッセージがストリーミングされ、クライアントに返されます。

フィールド
共用体フィールド converse_response。各 ConverseResponse には、これらのフィールドのいずれか 1 つのみが入力されます。converse_response は次のいずれかになります。
error

Status

出力のみ。設定された場合、オペレーションのエラーを指定する google.rpc.Status メッセージを返します。処理中にエラーが発生すると、このメッセージが設定され、それ以降は送信されなくなります。
event_type

EventType

出力のみ。イベントのタイプを示します。
audio_out

AudioOut

出力のみ。クエリに対するアシスタントのレスポンスを含む音声。
result

ConverseResult

出力のみ。ユーザーが発話したクエリのセマンティック結果。

EventType

イベントの種類を示します。

列挙型
EVENT_TYPE_UNSPECIFIED イベントは指定されていません。
END_OF_UTTERANCE このイベントは、サーバーがユーザーの発話の終わりを検出し、これ以上発話が続くことはないと推測したことを示します。したがって、サーバーは以降の音声を処理しません（ただし、後で追加の結果を返すことがあります）。クライアントは以降の音声データの送信を停止し、gRPC 接続を半分閉じて、サーバーが gRPC 接続を閉じるまで追加の結果を待機する必要があります。

ConverseResult

ユーザーの音声クエリのセマンティック結果。

フィールド
spoken_request_text

string

出力のみ。ユーザーの発話の認識された音声文字変換。
spoken_response_text

string

出力のみ。アシスタントの音声レスポンスのテキスト。IFTTT アクションの場合にのみ返されます。

conversation_state

bytes

出力のみ。後続の ConverseRequest の状態情報。この値はクライアントに保存し、次の ConverseRequest で conversation_state で返す必要があります。（クライアントはこの値を解釈したり使用したりする必要はありません）。この情報はデバイスの再起動で保存する必要はありません。

microphone_mode

MicrophoneMode

出力のみ。この Converse RPC が処理された後のマイクのモードを指定します。
volume_percentage

int32

出力のみ。更新された音量レベル。「音量を上げて」や「音量を 4 に設定して」などの音声コマンドが認識された場合、値は 1～100 になります（新しい音量レベル 1% から 100% に対応します）。それ以外の場合、値は 0 に設定されるか、省略されます（変更なしを意味します）。通常、クライアントは audio_out データの再生時にこの音量レベルを使用し、この値を現在の音量レベルとして保持して、次の ConverseRequest の AudioOutConfig で指定する必要があります。（クライアントによっては、ユーザーが回せるノブを提供するなど、現在の音量レベルを変更できる他の方法を実装している場合もあります）。

MicrophoneMode

Converse RPC が完了した後のマイクの状態。

列挙型
MICROPHONE_MODE_UNSPECIFIED モードが指定されていません。
CLOSE_MICROPHONE サービスはユーザーから続きの質問は来ないと推測しました。ユーザーが再びマイクを作動させるまで、マイクはオフのままになります。
DIALOG_FOLLOW_ON サービスはユーザーから続きの質問が来ると推測しました。AudioOut の再生が完了したら（新しい音声を送信するための新しい Converse RPC 呼び出しを開始して）マイクを再度開く必要があります。

ConverseState

現在の対話の状態に関する情報を提供します。

フィールド
conversation_state

bytes

必須。以前の ConverseResponse で返された conversation_state 値。先行する ConverseResponse がない場合は省略します（このフィールドは設定しないでください）。以前の ConverseResponse がある場合は、このフィールドを省略しないでください。この操作を行うと、その会話が終了します（この新しいリクエストによって新しい会話が開始されます）。