Package google.assistant.embedded.v1alpha2

索引

EmbeddedAssistant

執行 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 助理回應「好,我已經將貝果加入購物清單」。系統會將此呼叫當做另一個對 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

詳情請參閱驗證指南

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

要傳送至 Google 助理的文字輸入內容。如果無法使用音訊輸入功能,可透過文字介面填入這項資訊。

AssistRequest

用戶端傳送的頂層訊息。用戶端必須傳送至少兩則,且通常有多則 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

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

audio_out

AudioOut

僅限輸出:含有 Google 助理對查詢回應的音訊。

screen_out

ScreenOut

僅限輸出:包含 Google 助理對查詢的視覺化回應。

device_action

DeviceAction

僅限輸出:包含查詢觸發的動作,其中包含適當的酬載和語意剖析。

speech_results[]

SpeechRecognitionResult

僅限輸出:這份重複清單包含 0 個或多個的語音辨識結果,對應到目前處理中音訊的連續部分,從最早的音訊 (以及最穩定的部分) 對應至最新音訊的部分。您可以串連這些字串,以查看完整的處理中回應。語音辨識完成後,這份清單會包含 stability1.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 中的所有欄位。

AudioOut

包含 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。取樣率會在酬載中編碼。

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

如果使用者觸發了裝置動作,就會傳回裝置的回應。舉例來說,支援查詢「Turn on the light」的裝置會收到 DeviceAction,當中包含內含要求語意的 JSON 酬載。

欄位
device_request_json

string

包含觸發裝置動作文法的裝置指令回應的 JSON,格式由特定特徵action.devices.EXECUTE 意圖提供。

DeviceConfig

「必填」欄位,方便 Google 助理識別裝置。

另請參閱:

欄位
device_id

string

必填:裝置的專屬 ID。ID 長度不得超過 128 個半形字元。例如:DBCDW098234。這個 ID 必須與裝置註冊時傳回的 device_id 相符。此 device_id 會比對使用者已註冊的裝置,以便查詢這部裝置支援的 traits。這項資訊不會在裝置重新啟動後變更。不過,請勿在恢復原廠設定後儲存此密碼。

device_model_id

string

必填。裝置型號的專屬 ID。device_model_id 和 device_id 的組合必須與先前透過裝置註冊建立關聯。

DeviceLocation

地點有三個來源,這些屬性會用於以下優先順序:

  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

僅限輸出:由 Google 助理提供的補充顯示文字。這可能與 AssistResponse.audio_out 中的語音內容相同,也可能是一些有助於使用者理解的額外資訊。

conversation_state

bytes

僅限輸出:後續 Assist RPC 的狀態資訊。這個值應儲存在用戶端中,並在 DialogStateIn.conversation_state 欄位中傳回,並在下一個 Assist 遠端程序呼叫 (RPC)。(用戶端不必解讀或以其他方式使用這個值)。這項資訊應會在裝置重新啟動後儲存。不過,恢復原廠設定時,系統會清除這個值 (而非儲存在用戶端中)。

microphone_mode

MicrophoneMode

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

volume_percentage

int32

僅限輸出:已更新音量等級。這個值會是 0 或省略 (表示沒有變更),除非辨識出「調高音量」或「將音量調到 4」等語音指令。在在這種情況下,該值介於 1 到 100 之間 (新音量的目標等級為 1% 至 100%)。一般來說,用戶端在播放 audio_out 資料時應使用這個磁碟區等級,並將這個值保留為目前的音量等級,並在下一個 AssistRequestAudioOutConfig 中提供這個值。(某些用戶端也可能採用其他方式來允許變更目前音量,例如提供可讓使用者轉動的旋鈕)。

MicrophoneMode

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

列舉
MICROPHONE_MODE_UNSPECIFIED 未指定模式。
CLOSE_MICROPHONE 這項服務不會預期使用者會持續提出問題。麥克風應保持關閉狀態,直到使用者重新啟用為止。
DIALOG_FOLLOW_ON 服務預期使用者會持續回答問題。當 AudioOut 播放完畢時,麥克風應該會重新開啟 (方法是啟動新的 Assist RPC 呼叫來傳送新音訊)。

ScreenOut

Google 助理的視覺化輸出回應。由 screen_out_config 啟用。

欄位
format

Format

僅限輸出:所提供畫面資料的格式。

data

bytes

僅限輸出:做為 Google 助理查詢結果顯示的原始畫面資料。

形式

可能的螢幕資料格式。

列舉
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 未指定影片模式。Google 助理可能會以OFF模式回應。
OFF 螢幕已關閉 (或是亮度或其他設定導致使用者看不到)。在這種模式下,Google 助理通常不會傳回螢幕回應。
PLAYING Google 助理通常在此模式下傳回部分畫面回應。

SpeechRecognitionResult

使用者所說詞組的預估語音轉錄。可以是單一區段,或是使用者語音查詢的完整猜測。

欄位
transcript

string

僅限輸出的轉錄稿文字,代表使用者叫用的字詞。

stability

float

僅限輸出:Google 助理不會變更這項結果的猜測機率預估值。值的範圍介於 0.0 (完全不穩定) 到 1.0 (完全穩定和最終) 之間。預設的 0.0 是 sentinel 值,表示未設定 stability