Package google.assistant.embedded.v1alpha2

索引

EmbeddedAssistant

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

アシスト

rpc Assist(AssistRequest) returns (AssistResponse)

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

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

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript "add to my shopping list"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

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

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.dialog_state_out.microphone_mode.CLOSE_MICROPHONE
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

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

認可スコープ

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

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

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

AssistConfig

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

フィールド
audio_out_config

AudioOutConfig

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

ScreenOutConfig

省略可。サーバーが視覚的な画面レスポンスを返すときに使用する形式を指定します。
dialog_state_in

DialogStateIn

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

device_config

DeviceConfig

特定のデバイスを一意に識別するデバイス設定。

debug_config

DebugConfig

省略可。Assist RPC 全体のデバッグ パラメータ。

共用体フィールド type。

type は次のいずれかになります。
audio_in_config

AudioInConfig

後から受信する音声の処理方法を指定します。後続のリクエストで AssistRequest.audio_in バイトが提供される場合は必須です。
text_query

string

アシスタントに送信するテキスト入力。音声入力が利用できない場合は、テキスト インターフェースから入力できます。

AssistRequest

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

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

AssistConfig

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

bytes

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

AssistResponse

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

フィールド
event_type

EventType

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

AudioOut

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

ScreenOut

出力のみ。クエリに対するアシスタントの視覚的なレスポンスが含まれます。
device_action

DeviceAction

出力のみ。クエリによってトリガーされたアクションと、適切なペイロードおよびセマンティック解析が含まれます。
speech_results[]

SpeechRecognitionResult

出力のみ。この繰り返しリストには、現在処理中の連続した音声に対応する音声認識結果が含まれます。結果はゼロ個のこともあり、最も古い音声（最も安定した部分）から最新の音声に対応する部分の順に格納されます。文字列を連結することで、進行中の完全なレスポンスを表示できます。音声認識が完了すると、このリストには、stability が 1.0 のアイテムが 1 つ含まれます。
dialog_state_out

DialogStateOut

出力のみ。ユーザーのクエリに関連する出力が含まれます。
debug_info

DebugInfo

出力のみ。デベロッパー向けのデバッグ情報。リクエストで return_debug_info が true に設定された場合にのみ返されます。

EventType

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

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

AudioInConfig

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

フィールド
encoding

Encoding

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

int32

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

エンコード

音声メッセージで送信されるデータの音声エンコード。音声は 1 チャンネル（モノラル）である必要があります。

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

AudioOut

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

フィールド
audio_data

bytes

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

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 よりもかなり高くなります。サンプリング レートはペイロードでエンコードされます。

DebugConfig

現在のリクエストのデバッグ パラメータ。

フィールド
return_debug_info

bool

このフィールドを true に設定すると、AssistResponse の debug_info フィールドに値が入力されます。ただし、レスポンスのレイテンシが大幅に増加します。

DebugInfo

デベロッパー向けのデバッグ情報。リクエストで return_debug_info が true に設定された場合にのみ返されます。

フィールド
aog_agent_to_assistant_json

string

Action-on-Google エージェントから Google サーバーへの元の JSON レスポンス。AppResponse をご覧ください。リクエスト作成者が AoG プロジェクトを所有し、AoG プロジェクトがプレビュー モードの場合にのみ入力されます。

DeviceAction

ユーザーがデバイス アクションをトリガーしたときに、デバイスに返されるレスポンスです。たとえば、「ライトをつけて」というクエリをサポートするデバイスは、リクエストのセマンティクスを含む JSON ペイロードを持つ DeviceAction を受け取ります。

フィールド
device_request_json

string

トリガーされたデバイス アクションの文法から生成されたデバイス コマンド レスポンスを含む JSON。この形式は、特定のトレイトの action.devices.EXECUTE インテントによって指定されます。

DeviceConfig

アシスタントがデバイスの識別に使用する必須フィールド。

関連項目:

フィールド
device_id

string

必須。デバイスの一意の識別子。ID の長さは 128 文字以下にする必要があります。例: DBCDW098234。これは、デバイス登録から返された device_id と一致している必要があります。この device_id をユーザーの登録済みデバイスと照合し、このデバイスのサポートされているトレイトと機能を検索します。この情報は、デバイスを再起動しても変化してはいけません。ただし、出荷時のデフォルト設定へのリセットでは保存しないでください。

device_model_id

string

必須。デバイスモデルの一意の識別子。device_model_id と device_id の組み合わせは、デバイス登録を通じて事前に関連付けられている必要があります。

DeviceLocation

ロケーションのソースは 3 つあります。次の優先順位で使用されます。

  1. この DeviceLocation は、主に GPS 搭載のモバイル デバイスで使用します。
  2. デバイスをセットアップするときにユーザーが指定したロケーション。ユーザーごと、デバイスごとに異なります。このロケーションは、DeviceLocation が指定されていない場合に使用されます。
  3. IP アドレスから推定されたロケーション。これは、上記のいずれも指定されていない場合にのみ使用されます。
フィールド
coordinates

LatLng

デバイスの緯度と経度。

DialogStateIn

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

フィールド
conversation_state

bytes

必須。このフィールドは、常に以前の Assist RPC で返された DialogStateOut.conversation_state 値に設定する必要があります。これは、以前の Assist RPC がなかった場合にのみ省略する必要があります（これは、初回セットアップまたは出荷時設定へのリセットの後にこのデバイスによって行われる最初の Assist RPC です）。

language_code

string

必須。IETF BCP 47 構文でのリクエストの言語（例: en-US）。詳しくは、言語サポートをご覧ください。スマートフォンの Google アシスタント アプリの [設定] メニューでこの device_id の言語を選択した場合、その選択内容はこの値よりも優先されます。

device_location

DeviceLocation

省略可。クエリを送信したデバイスのロケーション。
is_new_conversation

bool

省略可。true の場合、サーバーはリクエストを新しい会話として扱い、前のリクエストの状態を使用しません。デバイスの再起動後、または前のクエリからかなりの時間が経過した後など、会話を再開する必要がある場合は、このフィールドを true に設定します。

DialogStateOut

ユーザーのクエリによって発生する対話の状態。このメッセージは複数受信されることがあります。

フィールド
supplemental_display_text

string

出力のみ。アシスタントからの補助表示テキスト。これは、AssistResponse.audio_out で話されている音声と同じものでも、ユーザーの理解を助ける追加情報の場合もあります。
conversation_state

bytes

出力のみ。後続の Assist RPC の状態情報。この値はクライアントに保存し、次の Assist RPC で DialogStateIn.conversation_state フィールドに返す必要があります。（クライアントはこの値を解釈したり使用したりする必要はありません）。この情報は、デバイスを再起動しても保存されます。ただし、出荷時設定へのリセット時に、この値はクリアする（クライアントに保存しない）必要があります。

microphone_mode

MicrophoneMode

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

int32

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

MicrophoneMode

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

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

ScreenOut

クエリに対するアシスタントの視覚的出力レスポンス。screen_out_config によって有効にされました。

フィールド
format

Format

出力のみ。提供された画面データの形式。
data

bytes

出力のみ。アシスタント クエリの結果として表示される未加工画面データ。

形式

画面データの形式。

列挙型
FORMAT_UNSPECIFIED 形式が指定されていません。
HTML データには、UTF-8 でエンコードされた完全な形式の HTML5 レイアウトが含まれます（例: <html><body><div>...</div></body></html>）。音声レスポンスとともにレンダリングされることを意図しています。HTML5 doctype を実際の HTML データに含める必要があります。

ScreenOutConfig

サーバーが screen_out レスポンスを返す際に使用する形式を指定します。

フィールド
screen_mode

ScreenMode

クエリ発行時のデバイスの現在の視覚的な画面モード。

ScreenMode

デバイスの視覚的な画面出力のモード。

列挙型
SCREEN_MODE_UNSPECIFIED 動画モードが指定されていません。アシスタントは OFF モードの場合と同様に応答します。
OFF 画面はオフです（あるいは、明るさまたはその他の設定が低く、見ることができません）。アシスタントは通常、このモードでは画面レスポンスを返しません。
PLAYING アシスタントは通常、このモードで部分画面レスポンスを返します。

SpeechRecognitionResult

ユーザーが話したフレーズの推定字幕。これは、ユーザーの音声クエリの完全な推測または単一のセグメントです。

フィールド
transcript

string

出力のみ。ユーザーが発話した単語を表す音声文字変換テキスト。
stability

float

出力のみ。アシスタントがこの結果の推測を変更しない可能性の推定値。値の範囲は、0.0（完全に不安定）から 1.0（完全に安定、最終状態）です。デフォルトの 0.0 は、stability が設定されていないことを示す標識値です。