Package google.assistant.embedded.v1alpha2

Indice

EmbeddedAssistant

Servizio che implementa l'API Google Assistant.

Assist

rpc Assist(AssistRequest) returns (AssistResponse)

Avvia o continua una conversazione con il servizio assistente incorporato. Ogni chiamata esegue un round trip, inviando una richiesta audio al servizio e ricevendo la risposta audio. Utilizza lo streaming bidirezionale per ricevere risultati, ad esempio l'evento END_OF_UTTERANCE, durante l'invio dell'audio.

Una conversazione consiste in una o più connessioni gRPC, ciascuna composta da diverse richieste e risposte in modalità flusso. Ad esempio, l'utente dice Aggiungi alla mia lista della spesa e l'assistente risponde Cosa vuoi aggiungere?. La sequenza di richieste e risposte in modalità flusso nel primo messaggio gRPC potrebbe essere:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.Speech_results.transcript "aggiungi alla mia lista della spesa"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

L'utente dice bagel e l'assistente risponde Ok, ho aggiunto i bagel alla tua lista della spesa. Viene inviata come un'altra chiamata di connessione gRPC al metodo Assist, sempre con richieste e risposte in streaming, ad esempio:

  • 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

Sebbene l'ordine preciso delle risposte non sia garantito, i messaggi AssistResponse.audio_out sequenziali includeranno sempre porzioni di audio sequenziali.

Ambiti di autorizzazione

Richiede il seguente ambito OAuth:

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

Per ulteriori informazioni, consulta la Guida all'autenticazione.

AssistConfig

Specifica come elaborare i messaggi AssistRequest.

Campi
audio_out_config

AudioOutConfig

Obbligatorio Specifica la formattazione dell'audio che verrà restituito.

screen_out_config

ScreenOutConfig

Facoltativo Specifica il formato desiderato da utilizzare quando il server restituisce una risposta della schermata visiva.

dialog_state_in

DialogStateIn

Obbligatorio Rappresenta lo stato corrente della finestra di dialogo.

device_config

DeviceConfig

Configurazione del dispositivo che identifica in modo univoco un dispositivo specifico.

debug_config

DebugConfig

Facoltativo Parametri di debug per l'intera RPC Assist.

Campo di unione type.

type può essere solo uno dei seguenti:
audio_in_config

AudioInConfig

Specifica come elaborare il successivo audio in arrivo. Obbligatorio se vengono forniti AssistRequest.audio_in byte nelle richieste successive.

text_query

string

L'input di testo da inviare all'assistente. Può essere compilato da un'interfaccia di testo se l'input audio non è disponibile.

AssistRequest

Il messaggio di primo livello inviato dal client. I client devono inviare almeno due messaggi AssistRequest, di solito numerosi. Il primo messaggio deve contenere un messaggio config e non deve contenere dati audio_in. Tutti i messaggi successivi devono contenere i dati audio_in e non un messaggio config.

Campi
Campo di unione type. È necessario specificare esattamente uno di questi campi in ogni AssistRequest. type può essere solo uno dei seguenti:
config

AssistConfig

Il messaggio config fornisce informazioni al riconoscimento che specificano come elaborare la richiesta. Il primo messaggio AssistRequest deve contenere un messaggio config.

audio_in

bytes

I dati audio da riconoscere. Pezzi sequenziali di dati audio vengono inviati in messaggi AssistRequest sequenziali. Il primo messaggio AssistRequest non deve contenere dati audio_in e tutti i messaggi AssistRequest successivi devono contenere dati audio_in. I byte audio devono essere codificati come specificato in AudioInConfig. L'audio deve essere inviato approssimativamente in tempo reale (16.000 campioni al secondo). Se l'audio viene inviato molto più velocemente o più lentamente, verrà restituito un errore.

AssistResponse

Il messaggio di primo livello ricevuto dal client. Una serie di uno o più messaggi AssistResponse viene riprodotta in streaming al client.

Campi
event_type

EventType

Solo output Indica il tipo di evento.

audio_out

AudioOut

Solo output: l'audio contenente la risposta dell'assistente alla query.

screen_out

ScreenOut

Output-only contiene la risposta visiva dell'assistente alla query.

device_action

DeviceAction

Solo output contiene l'azione attivata dalla query con i payload e l'analisi semantica appropriati.

speech_results[]

SpeechRecognitionResult

Solo output Questo elenco ripetuto contiene zero o più risultati del riconoscimento vocale corrispondenti a parti consecutive dell'audio attualmente in fase di elaborazione, a partire dalla parte corrispondente all'audio più recente (e alla parte più stabile) fino alla parte corrispondente all'audio più recente. Le stringhe possono essere concatenate per visualizzare la risposta completa in corso. Al termine del riconoscimento vocale, questo elenco conterrà una voce con stability di 1.0.

dialog_state_out

DialogStateOut

Solo output Contiene l'output relativo alla query dell'utente.

debug_info

DebugInfo

Solo output Informazioni di debug per lo sviluppatore. Restituito solo se la richiesta return_debug_info è impostata su true.

EventType

Indica il tipo di evento.

Enum
EVENT_TYPE_UNSPECIFIED Nessun evento specificato.
END_OF_UTTERANCE Questo evento indica che il server ha rilevato la fine dell'espressione vocale dell'utente e non prevede comandi vocali aggiuntivi. Di conseguenza, il server non elaborerà audio aggiuntivo (anche se in seguito potrebbe restituire risultati aggiuntivi). Il client dovrebbe interrompere l'invio di dati audio aggiuntivi, chiudere a metà la connessione gRPC e attendere eventuali risultati aggiuntivi finché il server non chiude la connessione gRPC.

AudioInConfig

Specifica come elaborare i dati di audio_in che verranno forniti nelle richieste successive. Per le impostazioni consigliate, consulta le best practice relative all'SDK dell'Assistente Google.

Campi
encoding

Encoding

Obbligatorio Codifica dei dati audio inviati in tutti i messaggi audio_in.

sample_rate_hertz

int32

Obbligatorio Frequenza di campionamento (in Hertz) dei dati audio inviati in tutti i messaggi audio_in. I valori validi sono compresi tra 16.000 e 24.000, ma 16.000 è ottimale. Per ottenere risultati ottimali, imposta la frequenza di campionamento della sorgente audio su 16.000 Hz. Se non è possibile, utilizza la frequenza di campionamento nativa della sorgente audio (anziché il ricampionamento).

Codifica

Codifica audio dei dati inviati nel messaggio audio. L'audio deve essere monocanale (mono).

Enum
ENCODING_UNSPECIFIED Non specificato. Verrà restituito il risultato google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Campioni L-endian firmati a 16 bit non compressi (PCM lineare). Questa codifica non include intestazioni, ma solo byte audio non elaborati.
FLAC FLAC (Free Lossless Audio Codec) è la codifica consigliata perché è senza perdita di dati, pertanto il riconoscimento non è compromesso, e richiede solo circa la metà della larghezza di banda di LINEAR16. Questa codifica include l'intestazione stream FLAC seguita dai dati audio. Supporta campioni a 16 e 24 bit, ma non tutti i campi in STREAMINFO sono supportati.

AudioOut

L'audio contenente la risposta dell'assistente alla query. I blocchi sequenziali di dati audio vengono ricevuti in messaggi AssistResponse sequenziali.

Campi
audio_data

bytes

Solo output I dati audio contenenti la risposta dell'assistente alla query. I blocchi sequenziali di dati audio vengono ricevuti in messaggi AssistResponse sequenziali.

AudioOutConfig

Specifica il formato che il server deve utilizzare per la restituzione dei messaggi audio_out.

Campi
encoding

Encoding

Obbligatorio La codifica dei dati audio da restituire in tutti i messaggi audio_out.

sample_rate_hertz

int32

Obbligatorio La frequenza di campionamento in Hertz dei dati audio restituiti nei messaggi audio_out. I valori validi sono: 16000-24000.

volume_percentage

int32

Obbligatorio Impostazione del volume attuale dell'uscita audio del dispositivo. I valori validi sono compresi tra 1 e 100 (corrispondenti all'1%-100%).

Codifica

Codifica audio dei dati restituiti nel messaggio audio. Tutte le codifiche sono byte audio non elaborati senza intestazione, ad eccezione di quanto indicato di seguito.

Enum
ENCODING_UNSPECIFIED Non specificato. Verrà restituito il risultato google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Campioni L-endian firmati a 16 bit non compressi (PCM lineare).
MP3 Codifica audio MP3. La frequenza di campionamento è codificata nel payload.
OPUS_IN_OGG Audio con codifica Opus racchiuso in un container ogg. Il risultato sarà un file che può essere riprodotto in modo nativo su Android e in alcuni browser (come Chrome). La qualità della codifica è notevolmente superiore a quella del formato MP3, pur utilizzando la stessa velocità in bit. La frequenza di campionamento è codificata nel payload.

DebugConfig

Parametri di debug per la richiesta attuale.

Campi
return_debug_info

bool

Se questo campo è impostato su true, il campo debug_info in AssistResponse può essere compilato. Tuttavia, aumenterà notevolmente la latenza delle risposte.

DebugInfo

Informazioni di debug per lo sviluppatore. Restituito solo se la richiesta return_debug_info è impostata su true.

Campi
aog_agent_to_assistant_json

string

La risposta JSON originale da un agente Action-on-Google al server Google. Vedi AppResponse. Verrà compilato solo se l'autore della richiesta è proprietario del progetto AoG e quest'ultimo è in modalità di anteprima.

DeviceAction

La risposta è stata restituita al dispositivo se l'utente ha attivato un'azione dispositivo. Ad esempio, un dispositivo che supporta la query Accendi la luce riceverebbe un DeviceAction con un payload JSON contenente la semantica della richiesta.

Campi
device_request_json

string

JSON contenente la risposta del comando del dispositivo generata dalla grammatica dell'Azione dispositivo attivata. Il formato viene fornito dall'intent action.devices.EXECUTE per un determinato trait.

DeviceConfig

Obbligatorio Campi che identificano il dispositivo per l'assistente.

Vedi anche:

Campi
device_id

string

Obbligatorio Identificatore univoco del dispositivo. La lunghezza dell'ID deve essere al massimo di 128 caratteri. Esempio: DBCDW098234. DEVE corrispondere al device_id restituito dalla registrazione del dispositivo. Questo ID dispositivo viene utilizzato per creare corrispondenze con i dispositivi registrati dell'utente e cercare i trait e le funzionalità supportati di questo dispositivo. Queste informazioni non dovrebbero cambiare a seconda dei riavvii dei dispositivi. Tuttavia, non deve essere salvato dopo i ripristini dei valori di fabbrica.

device_model_id

string

Obbligatorio Identificatore univoco per il modello di dispositivo. La combinazione di device_model_id e device_id deve essere stata precedentemente associata tramite la registrazione del dispositivo.

DeviceLocation

Le origini delle posizioni sono tre. Vengono utilizzati con questa precedenza:

  1. Questo DeviceLocation, utilizzato principalmente per i dispositivi mobili con GPS .
  2. Località specificata dall'utente durante la configurazione del dispositivo; la posizione è per utente e per dispositivo. Questa località viene utilizzata se DeviceLocation non è specificato.
  3. Località dedotta in base all'indirizzo IP. Viene utilizzato solo se nessuna delle opzioni precedenti è specificata.
Campi
coordinates

LatLng

Latitudine e longitudine del dispositivo.

DialogStateIn

Fornisce informazioni sullo stato attuale della finestra di dialogo.

Campi
conversation_state

bytes

Obbligatorio Questo campo deve essere sempre impostato sul valore DialogStateOut.conversation_state restituito nell'RPC Assist precedente. Deve essere omesso (campo non impostato) solo se non sono stati eseguiti RPC Assist precedenti, perché questa è la prima RPC Assist effettuata da questo dispositivo dopo la prima configurazione e/o dopo un ripristino dei dati di fabbrica.

language_code

string

Obbligatorio Lingua della richiesta nella sintassi IETF BCP 47 (ad esempio, "en-US"). Per ulteriori informazioni, visita la pagina Supporto delle lingue. Se hai selezionato una lingua per questo device_id dal menu Impostazioni nell'app Assistente Google del telefono, la selezione sostituirà questo valore.

device_location

DeviceLocation

Facoltativo. Posizione del dispositivo da cui ha avuto origine la query.

is_new_conversation

bool

Facoltativo Se il valore è true, il server considera la richiesta come una nuova conversazione e non utilizza lo stato della richiesta precedente. Imposta questo campo su true quando la conversazione deve essere riavviata, ad esempio dopo il riavvio di un dispositivo o dopo un intervallo di tempo significativo dalla query precedente.

DialogStateOut

Lo stato della finestra di dialogo risultante dalla query dell'utente. Potrebbero essere ricevuti più messaggi di questo tipo.

Campi
supplemental_display_text

string

Solo output Testo visualizzato supplementare dall'assistente. Potrebbe essere lo stesso del parlato parlato in AssistResponse.audio_out oppure potrebbe trattarsi di alcune informazioni aggiuntive che facilitano la comprensione all'utente.

conversation_state

bytes

Solo output Informazioni sullo stato per la successiva RPC Assist. Questo valore dovrebbe essere salvato nel client e restituito nel campo DialogStateIn.conversation_state con l'RPC Assist successivo. Il cliente non deve interpretare né utilizzare in altro modo questo valore. Queste informazioni dovrebbero essere salvate nei riavvii dei dispositivi. Tuttavia, questo valore deve essere cancellato (non salvato nel client) durante un ripristino dei valori predefiniti di fabbrica.

microphone_mode

MicrophoneMode

Output-only Specifica la modalità del microfono dopo l'elaborazione di questa Assist RPC.

volume_percentage

int32

Solo output Livello del volume aggiornato. Il valore sarà 0 o omesso (che non indica alcuna modifica) a meno che non venga riconosciuto un comando vocale come Alza il volume o Imposta il livello del volume 4, nel qual caso il valore sarà compreso tra 1 e 100 (corrispondente al nuovo livello del volume, dall'1% al 100%). In genere, un client dovrebbe utilizzare questo livello di volume durante la riproduzione dei dati audio_out, mantenere questo valore come livello di volume attuale e fornirlo nella AudioOutConfig del AssistRequest successivo. Alcuni client potrebbero anche implementare altri metodi per modificare il livello del volume corrente, ad esempio fornendo una manopola che l'utente può ruotare.

MicrophoneMode

Possibili stati del microfono dopo il completamento di una RPC Assist.

Enum
MICROPHONE_MODE_UNSPECIFIED Nessuna modalità specificata.
CLOSE_MICROPHONE Il servizio non si aspetta una domanda successiva da parte dell'utente. Il microfono dovrebbe rimanere disattivato finché l'utente non lo riattiva.
DIALOG_FOLLOW_ON Il servizio attende una domanda successiva da parte dell'utente. Il microfono dovrebbe essere riaperto al termine della riproduzione AudioOut (avviando una nuova chiamata RPC Assist per inviare il nuovo audio).

ScreenOut

La risposta dell'output visivo dell'assistente alla query. Attivata da screen_out_config.

Campi
format

Format

Solo output Il formato dei dati dello schermo forniti.

data

bytes

Solo output I dati non elaborati dello schermo da visualizzare come risultato della query all'assistente.

Formato

Possibili formati dei dati delle schermate.

Enum
FORMAT_UNSPECIFIED Nessun formato specificato.
HTML I dati conterranno un layout HTML5 completo codificato in UTF-8, ad esempio <html><body><div>...</div></body></html>. Deve essere visualizzata insieme alla risposta audio. Tieni presente che il doctype HTML5 deve essere incluso nei dati HTML effettivi.

ScreenOutConfig

Specifica il formato che il server deve utilizzare quando restituisce la risposta screen_out.

Campi
screen_mode

ScreenMode

Modalità di visualizzazione dello schermo corrente per il dispositivo durante l'invio della query.

ScreenMode

Possibili modalità di visualizzazione dello schermo sul dispositivo.

Enum
SCREEN_MODE_UNSPECIFIED Nessuna modalità video specificata. L'assistente potrebbe rispondere come se fosse in modalità OFF.
OFF Lo schermo è spento (oppure la luminosità o altre impostazioni sono impostate su un valore così basso da non essere visibile). In genere l'assistente non restituisce una risposta dello schermo in questa modalità.
PLAYING In genere, in questa modalità l'assistente restituisce una risposta a schermo parziale.

SpeechRecognitionResult

La trascrizione stimata di una frase pronunciata dall'utente. Potrebbe trattarsi di un singolo segmento o dell'ipotesi completa della query pronunciata dall'utente.

Campi
transcript

string

Solo output Testo della trascrizione che rappresenta le parole pronunciate dall'utente.

stability

float

Solo output Una stima della probabilità che l'assistente non cambi la sua ipotesi su questo risultato. I valori vanno da 0,0 (completamente instabile) a 1,0 (completamente stabile e finale). Il valore predefinito 0,0 è un valore sentinel che indica che stability non è stato impostato.