Package google.assistant.embedded.v1alpha1

索引

EmbeddedAssistant

導入 Google 助理 API 的服務。

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

啟動或繼續與嵌入式助理服務的對話。每個呼叫都會執行一次往返作業，將音訊要求傳送至服務，並接收音訊回應。在傳送音訊時，使用雙向串流接收結果 (例如 END_OF_UTTERANCE 事件)。

對話指的是一或多個 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

接著，使用者說「貝果」，Google 助理就會回應「好，我已經將貝果加入購物清單」。系統會將此呼叫當做另一個對 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

詳情請參閱驗證指南。

AudioInConfig

指定如何處理後續要求中提供的 audio_in 資料。如需建議設定，請參閱 Google 助理 gRPC API 最佳做法。

欄位
encoding

Encoding

必填：在所有 audio_in 訊息中傳送的音訊資料編碼。

sample_rate_hertz

int32

必填：在所有 audio_in 訊息中傳送的音訊資料取樣率 (單位為 Hertz)。有效值介於 16000 至 24000 之間，16000 是最佳值。為獲得最佳效果，請將音訊來源的取樣率設為 16000 Hz。如果無法這麼做，請使用音訊來源的原始取樣率 (而非重新取樣)。

編碼

語音訊息傳送的資料音訊編碼。音訊必須為單一頻道 (單聲道)。唯一支援的語言是「en-US」。

列舉
ENCODING_UNSPECIFIED 未指定，將傳回 google.rpc.Code.INVALID_ARGUMENT 結果。
LINEAR16 未壓縮的 16 位元已簽署 Little-Endian 樣本 (線性 PCM)。這個編碼不包含標頭，只有原始音訊位元組。
FLAC 建議採用 FLAC (自由無損音訊轉碼器) 編碼，因為這種編碼不會失真 (因此不會受損，且只需約 LINEAR16 的一半頻寬)。這個編碼包括 FLAC 串流標頭和音訊資料。不過，可支援 16 位元和 24 位元樣本，但不支援 STREAMINFO 中的所有欄位。

AudioOut

包含 Google 助理對查詢的回應音訊。後續的 ConverseResponse 訊息會接收後續的音訊資料區塊。

欄位
audio_data

bytes

僅限輸出：包含 Google 助理對查詢的回應。後續的 ConverseResponse 訊息會接收後續的音訊資料區塊。

AudioOutConfig

指定伺服器傳回 audio_out 訊息時要使用的格式。

欄位
encoding

Encoding

必要：在所有 audio_out 訊息中傳回的音訊資料編碼。
sample_rate_hertz

int32

必填：audio_out 訊息中傳回的音訊資料赫茲取樣率。有效值為 16000-24000。
volume_percentage

int32

必填：裝置音訊輸出的目前音量設定。有效值為 1 到 100 (1% 等於 100%)。

編碼

語音訊息傳回的資料音訊編碼。所有編碼都是不含標頭的原始音訊位元組，但下文說明除外。

列舉
ENCODING_UNSPECIFIED 未指定，將傳回 google.rpc.Code.INVALID_ARGUMENT 結果。
LINEAR16 未壓縮的 16 位元帶正負號的小端序樣本 (線性 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

用戶端傳送的頂層訊息。用戶端必須傳送至少兩則，且通常有多則 ConverseRequest 訊息。第一則訊息必須包含 config 訊息，且不得包含 audio_in 資料。所有後續訊息都必須包含 audio_in 資料，且不得包含 config 訊息。

欄位
聯集欄位 converse_request。每個 ConverseRequest 中必須明確指定其中一個欄位。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 中只會填入其中一個欄位。converse_response 只能採用下列其中一種設定：
error

Status

僅限輸出：如果已設定，系統會傳回 google.rpc.Status 訊息，指定作業發生錯誤。如果處理過程中發生錯誤，系統會設定這則訊息，也不會再傳送任何訊息。

event_type

EventType

「僅限輸出」：指出事件類型。
audio_out

AudioOut

僅限輸出：包含 Google 助理對查詢的回應。

result

ConverseResult

僅限輸出：使用者語音查詢的語意結果。

EventType

表示活動類型。

列舉
EVENT_TYPE_UNSPECIFIED 未指定事件。
END_OF_UTTERANCE 這個事件表示伺服器偵測到使用者語音內容已結束，並認為沒有任何其他語音內容。因此，伺服器不會處理任何其他音訊內容 (雖然後續可能傳回其他結果)。用戶端應停止傳送其他音訊資料、半關閉 gRPC 連線，並等待任何其他結果，直到伺服器關閉 gRPC 連線為止。

ConverseResult

使用者語音查詢的語意結果。

欄位
spoken_request_text

string

僅限輸出：使用者所說內容的可辨識轉錄稿。
spoken_response_text

string

僅限輸出：Google 助理的語音回應文字。只有 IFTTT 動作才會傳回這個字串。
conversation_state

bytes

僅限輸出：後續 ConverseRequest 的狀態資訊。這個值應儲存在用戶端中，並以下一個 ConverseRequest 傳回 conversation_state。(用戶端不必解讀或以其他方式使用這個值)。這樣您在裝置重新啟動時就不需要儲存這項資訊。

microphone_mode

MicrophoneMode

「僅限輸出」：指定這個 Converse 遠端程序呼叫 (RPC) 處理完成後的麥克風模式。
volume_percentage

int32

僅限輸出：已更新音量等級。這個值會是 0 或省略 (表示沒有變更)，除非辨識出「調高音量」或「將音量調到 4」等語音指令，也就是該值介於 1 到 100 (對應最高音量 1% 至 100%) 之間。一般來說，用戶端在播放 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，請勿略過這個欄位，這麼做會結束該對話 (且這項新要求會發起新對話)。