Package google.assistant.embedded.v1alpha2

索引

內嵌式 Google 助理

實作 Google 助理 API 的服務。

助攻

rpc Assist(AssistRequest) returns (AssistResponse)

透過內嵌的 Google 助理服務發起或繼續對話。每次呼叫都會執行一次來回要求，將音訊要求傳送至服務並接收音訊回應。使用雙向串流來接收結果，例如在傳送音訊時 END_OF_UTTERANCE。

對話是指一或多個 gRPC 連線，每個連線都包含多個串流要求和回應。舉例來說，使用者說出「加入我的購物清單」，Google 助理就會回應「您想新增什麼？」。第一個 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 「加入我的購物清單」
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

然後，使用者說「貝果」，而 Google 助理回應「好，我已將購物車加入購物車」。這會將另一個 gRPC 連線呼叫傳送至 Assist 方法，再次使用串流要求和回應，例如：

  • 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

詳情請參閱驗證指南。

輔助設定

指定 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

要傳送給 Google 助理的文字輸入內容。如果沒有音訊輸入，則可從文字介面填入。

協助要求

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

欄位
聯集欄位 type。每個 AssistRequest 都必須明確指定其中一個欄位。type 只能是下列其中一個值：
config

AssistConfig

config 訊息會向辨識器提供資訊，指定要求的處理方式。第一則 AssistRequest 訊息必須包含 config 訊息。
audio_in

bytes

要辨識的音訊資料。連續的音訊資料區塊會依序 AssistRequest 訊息傳送。第一則 AssistRequest 訊息不得包含 audio_in 資料，但所有後續的 AssistRequest 訊息都必須包含 audio_in 資料。音訊位元組必須依照 AudioInConfig 中指定的方式進行編碼。音訊必須以近乎即時的速度 (每秒 16,000 個樣本)如果音訊的播放速度明顯變慢，系統會傳回錯誤訊息。

AssistResponse

用戶端接收的頂層訊息。一或多則 AssistResponse 訊息會串流至用戶端。

欄位
event_type

EventType

Output-only 表示事件類型。

audio_out

AudioOut

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

screen_out

ScreenOut

僅供輸出：包含 Google 助理在查詢時的視覺回應。

device_action

DeviceAction

僅限輸出：包含查詢觸發的動作，以及適當的酬載和語意剖析。
speech_results[]

SpeechRecognitionResult

僅限輸出：這份重複清單包含 0 個或更多的語音辨識結果。這些結果會對應到目前處理的音訊部分，且從與最近音訊 (和最穩定的部分) 對應的部分開始，與最近音訊對應的部分。字串可以串連起來，以便查看完整的進行中回應。語音辨識功能完成之後，這份清單會包含 1 個含有 stability 的 1.0 項目。
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 訊息中傳送的音訊資料取樣率 (以 Hertz 為準)。有效值介於 16000 到 24000 之間，但最好是 16000。為獲得最佳效果，請將音訊來源的取樣率設為 16000 Hz。如果無法做到，請使用音訊來源的原生取樣率 (而非重新取樣)。

編碼

語音訊息中傳送的資料音訊編碼。音訊須為單聲道 (單聲道)。

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

音訊輸出

包含 Google 助理回應查詢的音訊。依序傳送音訊資料區塊，AssistResponse 訊息。

欄位
audio_data

bytes

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

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 高出許多。取樣率會在酬載中經過編碼。

偵錯設定

對目前要求的參數進行偵錯。

欄位
return_debug_info

bool

將這個欄位設為 true 時，系統可能會填入 AssistResponse 中的 debug_info 欄位。但這麼做會大幅增加回應的延遲時間。

DebugInfo

開發人員的偵錯資訊。只有在要求 return_debug_info 設為 true 時才會傳回。

欄位
aog_agent_to_assistant_json

string

從 Actions on Google 代理程式傳送至 Google 伺服器的原始 JSON 回應。請參閱 AppResponse。只有在要求者擁有 AoG 專案，且 AoG 專案處於預覽模式時，系統才會填入這項資訊。

裝置動作

如果使用者觸發裝置動作，回應就會傳回裝置。例如，支援查詢「開啟燈具」的裝置會收到 DeviceAction，其 JSON 酬載包含要求的語意。

欄位
device_request_json

string

JSON 包含從觸發的裝置動作文法產生的裝置指令回應。此格式是由指定trait 的 action.devices.EXECUTE 意圖提供。

DeviceConfig

必填欄位：供 Google 助理辨識裝置。

另請參閱：

欄位
device_id

string

要求的必填裝置 ID。ID 長度不得超過 128 個字元。例如：DBCDW098234。這個值「必須」與裝置註冊所傳回的 device_id 相符。device_id 會和使用者註冊的裝置進行比對，以便查詢這部裝置支援的支援的特性和功能。本資訊不應隨著裝置重新啟動而改變。不過，我們不建議將裝置恢復原廠設定。

device_model_id

string

此為裝置型號的不重複 ID。device_model_id 和 device_id 的組合必須先前已透過裝置註冊建立關聯。

裝置位置

有三種位置來源。這些優先順序具有以下優先順序：

  1. 這個 DeviceLocation，主要用於具有 GPS 的行動裝置。
  2. 使用者在裝置設定期間指定的位置；每部裝置是按照使用者為單位。如未指定 DeviceLocation，會使用這個地點。
  3. 根據 IP 位址推斷出的位置。只有在未指定上述任一項目時，才需要使用這個屬性。
欄位
coordinates

LatLng

裝置的緯度和經度。

對話方塊狀態

提供目前對話方塊狀態的相關資訊。

欄位
conversation_state

bytes

必要：這個欄位必須設為前一個 Assist RPC 中傳回的 DialogStateOut.conversation_state 值。只有先前沒有 Assist RPC 時，才能略過 (未設定) 之前的 RPC，因為這是裝置在第一次設定和/或恢復原廠設定之後產生的第一個 Assist RPC。
language_code

string

要求的必填 (使用 IETF BCP 47 語法)，例如「en-US」。詳情請參閱「語言支援」。如果您在手機的 Google 助理應用程式中透過「設定」選單選取了這個 device_id 的語言，選取的選項就會覆寫這個值。

device_location

DeviceLocation

「選填」查詢的來源裝置位置。

is_new_conversation

bool

選填：如果為 true，伺服器會將要求視為新的對話，且不會使用先前要求的狀態。請將這個欄位設為 true，例如重新啟動裝置後，例如裝置重新啟動後，或是上次查詢後經過短暫的時間。

對話方塊

使用者查詢產生的對話方塊狀態。系統可能會收到多則訊息。

欄位
supplemental_display_text

string

僅限輸出：Google 助理的補充顯示文字。這可以和 AssistResponse.audio_out 中的語音朗讀，也可以是可協助使用者理解的其他資訊。
conversation_state

bytes

僅限輸出 後續 Assist 遠端程序呼叫 (RPC) 的狀態資訊。這個值應儲存在用戶端，並透過下一個 Assist 遠端程序的 DialogStateIn.conversation_state 欄位傳回。(用戶端不需要解讀或以其他方式使用這個值)。請務必在裝置重新啟動後儲存這項資訊。不過，你必須在恢復原廠設定期間清除這個值 (不要儲存在用戶端中)。

microphone_mode

MicrophoneMode

僅供輸出：指定這個 Assist RPC 處理完畢後的麥克風模式。
volume_percentage

int32

僅限輸出：已更新音量等級。除非系統已偵測到類似「調高音量」或「設定音量 4」等語音指令，否則這個值會是 0 或省略 (代表不會變更)。一般來說，用戶端在播放 audio_out 資料時會使用這個音量等級，並將這個值保留為目前的音量等級，並在下一個 AssistRequest 的 AudioOutConfig 中提供該值。(部分用戶端也可以實作其他方法，來變更目前的音量等級，例如提供使用者可關閉的旋鈕)。

麥克風模式

完成 Assist RPC 後，麥克風的可能狀態。

列舉
MICROPHONE_MODE_UNSPECIFIED 未指定模式。
CLOSE_MICROPHONE 服務預期不會有使用者後續提出的疑問。麥克風應保持關閉狀態，直到使用者重新啟用為止。
DIALOG_FOLLOW_ON 服務預期會有使用者提出後續問題。AudioOut 播放完成後，應會開啟麥克風 (透過啟動新的 Assist RPC 呼叫來傳送新音訊)。

螢幕外

Google 助理在查詢時的視覺輸出回應。已於 screen_out_config啟用。

欄位
format

Format

僅限輸出：提供螢幕資料的格式。
data

bytes

僅限輸出：在 Google 助理查詢結果中顯示的原始畫面資料。

形式

畫面資料可能的格式。

列舉
FORMAT_UNSPECIFIED 未指定格式。
HTML 資料會包含採用 UTF-8 編碼的完整 HTML5 版面配置，例如 <html><body><div>...</div></body></html>。與音訊回應一併呈現。請注意，HTML5 DOCTYPE 已納入實際的 HTML 資料中。

螢幕外設定

指定伺服器在傳回 screen_out 回應時要使用的格式。

欄位
screen_mode

ScreenMode

發出查詢時，裝置目前的視覺畫面模式。

畫面模式

裝置視覺畫面輸出的可行模式。

列舉
SCREEN_MODE_UNSPECIFIED 未指定影片模式。Google 助理可能會以 OFF 模式回應。
OFF 螢幕已關閉 (或你調整了亮度或其他設定，因此畫面上未顯示)。Google 助理通常不會在這個模式下傳回畫面回應。
PLAYING Google 助理通常在這個模式下會傳回部分畫面的回應。

SpeechRecognitionResult

使用者說出的詞組預估轉錄內容。這可以是單一區隔，或是使用者所說查詢的完整猜測字詞。

欄位
transcript

string

僅限輸出：轉錄稿文字，代表使用者所說的字詞。
stability

float

僅限輸出：估算 Google 助理變更這項結果的可能性。以 0.0 (完全不穩定) 到 1.0 (完全穩定、最終) 之間的範圍表示。預設值為 0.0，表示未設定 stability。