索引
EmbeddedAssistant(介面)AssistConfig(訊息)AssistRequest(訊息)AssistResponse(訊息)AssistResponse.EventType(列舉)AudioInConfig(訊息)AudioInConfig.Encoding(列舉)AudioOut(訊息)AudioOutConfig(訊息)AudioOutConfig.Encoding(列舉)DebugConfig(訊息)DebugInfo(訊息)DeviceAction(訊息)DeviceConfig(訊息)DeviceLocation(訊息)DialogStateIn(訊息)DialogStateOut(訊息)DialogStateOut.MicrophoneMode(列舉)ScreenOut(訊息)ScreenOut.Format(列舉)ScreenOutConfig(訊息)ScreenOutConfig.ScreenMode(列舉)SpeechRecognitionResult(訊息)
EmbeddedAssistant
執行 Google 助理 API 的服務。
| 助攻 | |
|---|---|
|
啟動或繼續與嵌入的 Google 助理服務對話。每個呼叫都會執行一次往返作業，將音訊要求傳送至服務，並接收音訊回應。在傳送音訊時，使用雙向串流接收結果 (例如 對話指的是一或多個 gRPC 連線，每個連線都包含數個串流的要求和回應。例如，使用者說「加入我的購物清單」，Google 助理回應「你想新增什麼？」。第一則 gRPC 訊息中的串流要求和回應序列可能是：
接著，使用者說「貝果」，Google 助理回應「好，我已經將貝果加入購物清單」。系統會將此呼叫當做另一個對
雖然我們無法保證回應的確切順序，但依序處理的
|
|
AssistConfig
指定如何處理 AssistRequest 訊息。
| 欄位 | ||
|---|---|---|
audio_out_config |
必要：指定要傳回音訊的格式。 |
|
screen_out_config |
選填：指定伺服器傳回視覺化畫面回應時要使用的格式。 |
|
dialog_state_in |
必要：代表目前的對話方塊狀態。 |
|
device_config |
可明確識別特定裝置的裝置設定。 |
|
debug_config |
選填：整個 |
|
聯集欄位
|
||
audio_in_config |
指定如何處理後續傳入的音訊。如果在後續要求中提供 |
|
text_query |
要傳送至 Google 助理的文字輸入內容。如果無法使用音訊輸入功能，可透過文字介面填入這項資訊。 |
|
AssistRequest
用戶端傳送的頂層訊息。用戶端必須傳送至少兩則，且通常有多則 AssistRequest 訊息。第一則訊息必須包含 config 訊息，且不得包含 audio_in 資料。所有後續訊息都必須包含 audio_in 資料，且不得包含 config 訊息。
| 欄位 | ||
|---|---|---|
聯集欄位 type。每個 AssistRequest 中必須明確指定其中一個欄位。type 只能採用下列其中一種設定： |
||
config |
|
|
audio_in |
要辨識的音訊資料。後續的音訊資料區塊是用後續的 |
|
AssistResponse
用戶端收到的頂層訊息。系統會將一或多則 AssistResponse 訊息以串流方式傳回給用戶端。
| 欄位 | |
|---|---|
event_type |
「僅限輸出」：指出事件類型。 |
audio_out |
僅限輸出：含有 Google 助理對查詢回應的音訊。 |
screen_out |
僅限輸出：包含 Google 助理對查詢的視覺化回應。 |
device_action |
僅限輸出：包含查詢觸發的動作，其中包含適當的酬載和語意剖析。 |
speech_results[] |
僅限輸出：這份重複清單包含 0 個或多個的語音辨識結果，對應到目前處理中音訊的連續部分，從最早的音訊 (以及最穩定的部分) 對應至最新音訊的部分。您可以串連這些字串，以查看完整的處理中回應。語音辨識完成後，這份清單會包含 |
dialog_state_out |
僅限輸出：包含與使用者查詢相關的輸出內容。 |
debug_info |
僅限輸出：適用於開發人員的偵錯資訊。只有在要求將 |
EventType
表示活動類型。
| 列舉 | |
|---|---|
EVENT_TYPE_UNSPECIFIED |
未指定事件。 |
END_OF_UTTERANCE |
這個事件表示伺服器偵測到使用者語音內容已結束，並認為沒有任何其他語音內容。因此，伺服器不會處理任何其他音訊內容 (雖然後續可能傳回其他結果)。用戶端應停止傳送其他音訊資料、半關閉 gRPC 連線，並等待任何其他結果，直到伺服器關閉 gRPC 連線為止。 |
AudioInConfig
指定如何處理後續要求中提供的 audio_in 資料。如需建議設定，請參閱 Google 助理 SDK 最佳做法。
| 欄位 | |
|---|---|
encoding |
必填：在所有 |
sample_rate_hertz |
必填：在所有 |
編碼
語音訊息傳送的資料音訊編碼。音訊必須為單一頻道 (單聲道)。
| 列舉 | |
|---|---|
ENCODING_UNSPECIFIED |
未指定，將傳回 google.rpc.Code.INVALID_ARGUMENT 結果。 |
LINEAR16 |
未壓縮的 16 位元已簽署 Little-Endian 樣本 (線性 PCM)。這個編碼不包含標頭，只有原始音訊位元組。 |
FLAC |
建議採用 FLAC (自由無損音訊轉碼器) 編碼，因為這種編碼不會失真 (因此不會受損，且只需約 LINEAR16 的一半頻寬)。這個編碼包括 FLAC 串流標頭和音訊資料。不過，可支援 16 位元和 24 位元樣本，但不支援 STREAMINFO 中的所有欄位。 |
AudioOut
包含 Google 助理對查詢回應的音訊。後續的 AssistResponse 訊息會接收後續的音訊資料區塊。
| 欄位 | |
|---|---|
audio_data |
僅限輸出：包含 Google 助理對查詢的回應。後續的 |
AudioOutConfig
指定伺服器傳回 audio_out 訊息時要使用的格式。
| 欄位 | |
|---|---|
encoding |
必要：在所有 |
sample_rate_hertz |
必填： |
volume_percentage |
必填：裝置音訊輸出的目前音量設定。有效值為 1 到 100 (1% 等於 100%)。 |
編碼
語音訊息傳回的資料音訊編碼。所有編碼都是不含標頭的原始音訊位元組，但下文說明除外。
| 列舉 | |
|---|---|
ENCODING_UNSPECIFIED |
未指定，將傳回 google.rpc.Code.INVALID_ARGUMENT 結果。 |
LINEAR16 |
未壓縮的 16 位元帶正負號的小端序樣本 (線性 PCM)。 |
MP3 |
MP3 音訊編碼。取樣率會在酬載中編碼。 |
OPUS_IN_OGG |
包裝在 Ogg 容器中的 Opus 編碼音訊。產出結果將是可在 Android 和某些瀏覽器 (例如 Chrome) 中以原生方式播放的檔案。在使用相同位元率時，編碼的品質遠高於 MP3。取樣率會在酬載中編碼。 |
DebugConfig
目前要求的偵錯參數。
| 欄位 | |
|---|---|
return_debug_info |
如果這個欄位設為 true，系統可能會在 |
DebugInfo
給開發人員的偵錯資訊。只有在要求將 return_debug_info 設為 true 時才會傳回。
| 欄位 | |
|---|---|
aog_agent_to_assistant_json |
Action-on-Google 代理程式傳送到 Google 伺服器的原始 JSON 回應。請參閱「AppResponse」。只有在要求建立者擁有 AoG 專案，且 AoG 專案處於預覽模式時，系統才會填入這項資訊。 |
DeviceAction
如果使用者觸發了裝置動作，就會傳回裝置的回應。舉例來說，支援查詢「Turn on the light」的裝置會收到 DeviceAction，當中包含內含要求語意的 JSON 酬載。
| 欄位 | |
|---|---|
device_request_json |
包含觸發裝置動作文法的裝置指令回應的 JSON，格式由特定特徵的 |
DeviceConfig
「必填」欄位，方便 Google 助理識別裝置。
另請參閱：
| 欄位 | |
|---|---|
device_id |
必填：裝置的專屬 ID。ID 長度不得超過 128 個半形字元。例如：DBCDW098234。這個 ID 必須與裝置註冊時傳回的 device_id 相符。此 device_id 會比對使用者已註冊的裝置，以便查詢這部裝置支援的 traits。這項資訊不會在裝置重新啟動後變更。不過，請勿在恢復原廠設定後儲存此密碼。 |
device_model_id |
必填。裝置型號的專屬 ID。device_model_id 和 device_id 的組合必須與先前透過裝置註冊建立關聯。 |
DeviceLocation
地點有三個來源，這些屬性會用於以下優先順序：
- 此
DeviceLocation，主要用於搭載 GPS 的行動裝置。 - 使用者在設定裝置時指定的位置；這是每位使用者在每部裝置中的指定位置。如未指定
DeviceLocation，系統會使用這個位置。 - 根據 IP 位址推測位置。只有在未指定上述項目時，才能使用這個屬性。
| 欄位 | |
|---|---|
coordinates |
裝置的經緯度。 |
DialogStateIn
提供目前對話方塊狀態的相關資訊。
| 欄位 | |
|---|---|
conversation_state |
必要：這個欄位必須一律設為在先前 |
language_code |
必填：要求所使用的語言，並採用 IETF BCP 47 語法 (例如「en-US」)。詳情請參閱語言支援。如果您已透過手機的 Google 助理應用程式的「設定」選單為這個 |
device_location |
選填。查詢來源的裝置所在位置。 |
is_new_conversation |
選填。如果設為 true，伺服器會將要求視為新的對話，不會使用先前要求的狀態。當應重新啟動對話時 (例如裝置重新啟動，或在上次查詢經過經過大量時間後)，請將這個欄位設為 true。 |
DialogStateOut
使用者查詢產生的對話方塊狀態。可能會收到多則訊息。
| 欄位 | |
|---|---|
supplemental_display_text |
僅限輸出：由 Google 助理提供的補充顯示文字。這可能與 |
conversation_state |
僅限輸出：後續 |
microphone_mode |
「僅限輸出」：指定這個 |
volume_percentage |
僅限輸出：已更新音量等級。這個值會是 0 或省略 (表示沒有變更)，除非辨識出「調高音量」或「將音量調到 4」等語音指令。在在這種情況下，該值介於 1 到 100 之間 (新音量的目標等級為 1% 至 100%)。一般來說，用戶端在播放 |
MicrophoneMode
Assist RPC 完成後的麥克風可能狀態。
| 列舉 | |
|---|---|
MICROPHONE_MODE_UNSPECIFIED |
未指定模式。 |
CLOSE_MICROPHONE |
這項服務不會預期使用者會持續提出問題。麥克風應保持關閉狀態，直到使用者重新啟用為止。 |
DIALOG_FOLLOW_ON |
服務預期使用者會持續回答問題。當 AudioOut 播放完畢時，麥克風應該會重新開啟 (方法是啟動新的 Assist RPC 呼叫來傳送新音訊)。 |
ScreenOut
Google 助理的視覺化輸出回應。由 screen_out_config 啟用。
| 欄位 | |
|---|---|
format |
僅限輸出：所提供畫面資料的格式。 |
data |
僅限輸出：做為 Google 助理查詢結果顯示的原始畫面資料。 |
形式
可能的螢幕資料格式。
| 列舉 | |
|---|---|
FORMAT_UNSPECIFIED |
未指定格式。 |
HTML |
資料會包含採用 UTF-8 編碼的完整 HTML5 版面配置，例如 <html><body><div>...</div></body></html>。而是與音訊回應一起顯示。請注意，HTML5 doctype 應包含在實際的 HTML 資料中。 |
ScreenOutConfig
指定伺服器傳回 screen_out 回應時要使用的格式。
| 欄位 | |
|---|---|
screen_mode |
發出查詢時的裝置目前的螢幕模式。 |
ScreenMode
裝置上螢幕輸出模式可能的模式。
| 列舉 | |
|---|---|
SCREEN_MODE_UNSPECIFIED |
未指定影片模式。Google 助理可能會以OFF模式回應。 |
OFF |
螢幕已關閉 (或是亮度或其他設定導致使用者看不到)。在這種模式下，Google 助理通常不會傳回螢幕回應。 |
PLAYING |
Google 助理通常在此模式下傳回部分畫面回應。 |
SpeechRecognitionResult
使用者所說詞組的預估語音轉錄。可以是單一區段，或是使用者語音查詢的完整猜測。
| 欄位 | |
|---|---|
transcript |
僅限輸出的轉錄稿文字，代表使用者叫用的字詞。 |
stability |
僅限輸出：Google 助理不會變更這項結果的猜測機率預估值。值的範圍介於 0.0 (完全不穩定) 到 1.0 (完全穩定和最終) 之間。預設的 0.0 是 sentinel 值，表示未設定 |