Package google.assistant.embedded.v1alpha2

Índice

EmbeddedAssistant

Serviço que implementa a API Google Assistant.

Assistência

rpc Assist(AssistRequest) returns (AssistResponse)

Inicia ou continua uma conversa com o serviço do Google Assistente incorporado. Cada chamada realiza uma viagem de ida e volta, enviando uma solicitação de áudio ao serviço e recebendo a resposta de áudio. Usa streaming bidirecional para receber resultados, como o evento END_OF_UTTERANCE, ao enviar áudio.

Uma conversa é uma ou mais conexões gRPC, cada uma consistindo em várias solicitações e respostas transmitidas. Por exemplo, o usuário diz Adicionar à minha lista de compras, e o Google Assistente responde O que você quer adicionar?. A sequência das solicitações e respostas transmitidas na primeira mensagem gRPC pode ser:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript "adicionar à minha lista de compras"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

O usuário diz bagels, e o Google Assistente responde Ok, adicionei bagels à sua lista de compras. Isso é enviado como outra chamada de conexão gRPC para o método Assist, novamente com solicitações e respostas transmitidas, como:

  • 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

Ainda que a ordem precisa das respostas não seja garantida, as mensagens AssistResponse.audio_out sequenciais sempre terão partes sequenciais de áudio.

Escopos de autorização

Requer o seguinte escopo OAuth:

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

Para mais informações, consulte o Guia de autenticação.

AssistConfig

Especifica como processar as mensagens AssistRequest.

Campos
audio_out_config

AudioOutConfig

Obrigatório Especifica como formatar o áudio que será retornado.

screen_out_config

ScreenOutConfig

Opcional Especifica o formato desejado a ser usado quando o servidor retornar uma resposta visual da tela.

dialog_state_in

DialogStateIn

Obrigatório representa o estado atual da caixa de diálogo.

device_config

DeviceConfig

Configuração que identifica exclusivamente um dispositivo específico.

debug_config

DebugConfig

Opcional Parâmetros de depuração para toda a RPC Assist.

Campo de união type.

type pode ser apenas de um dos tipos a seguir:
audio_in_config

AudioInConfig

Especifica como processar o áudio de entrada seguinte. Obrigatório se AssistRequest.audio_in bytes forem fornecidos nas solicitações subsequentes.

text_query

string

A entrada de texto que será enviada ao Google Assistente. que poderá ser preenchido em uma interface de texto se a entrada de áudio não estiver disponível;

AssistRequest

A mensagem de nível superior enviada pelo cliente. Os clientes precisam enviar pelo menos duas e, normalmente, várias mensagens AssistRequest. A primeira mensagem precisa conter uma mensagem config e não pode conter dados audio_in. Todas as mensagens subsequentes precisam conter dados audio_in e não podem conter uma mensagem config.

Campos
Campo de união type. Exatamente um desses campos precisa ser especificado em cada AssistRequest. type pode ser apenas de um dos tipos a seguir:
config

AssistConfig

A mensagem config fornece informações ao reconhecedor que especificam como processar a solicitação. A primeira mensagem AssistRequest precisa conter uma mensagem config.

audio_in

bytes

Dados de áudio a serem reconhecidos. Os blocos sequenciais de dados de áudio são enviados em mensagens AssistRequest sequenciais. A primeira mensagem AssistRequest não pode conter dados audio_in, e todas as mensagens AssistRequest subsequentes precisam conter dados audio_in. Os bytes de áudio precisam ser codificados conforme especificado em AudioInConfig. O áudio precisa ser enviado aproximadamente em tempo real (16.000 amostras por segundo). Um erro será retornado se o áudio for enviado significativamente mais rápido ou mais devagar.

AssistResponse

A mensagem de nível superior recebida pelo cliente. É feito streaming de uma ou mais mensagens AssistResponse de volta para o cliente.

Campos
event_type

EventType

Somente saída Indica o tipo de evento.

audio_out

AudioOut

Somente saída: o áudio que contém a resposta do Google Assistente à consulta.

screen_out

ScreenOut

Somente saída: contém a resposta visual do Google Assistente à consulta.

device_action

DeviceAction

Somente saída: contém a ação acionada pela consulta com os payloads e a análise semântica adequados.

speech_results[]

SpeechRecognitionResult

Somente saída Esta lista repetida contém zero ou mais resultados de reconhecimento de fala que correspondem a porções consecutivas do áudio sendo processadas no momento, começando com a parte correspondente ao áudio mais antigo (e mais estável) até a parte correspondente ao áudio mais recente. As strings podem ser concatenadas para mostrar a resposta completa em andamento. Quando o reconhecimento de fala for concluído, a lista conterá um item com stability de 1.0.

dialog_state_out

DialogStateOut

Somente saída: contém a saída relacionada à consulta do usuário.

debug_info

DebugInfo

Somente saída Informações de depuração para o desenvolvedor. Retornará somente se a solicitação definir return_debug_info como "true".

EventType

Indica o tipo de evento.

Enums
EVENT_TYPE_UNSPECIFIED Nenhum evento especificado.
END_OF_UTTERANCE Esse evento indica que o servidor detectou o fim da fala do usuário e não espera nenhuma fala adicional. Portanto, o servidor não processará áudio adicional, ainda que possa retornar resultados adicionais posteriormente. O cliente deve parar de enviar dados de áudio adicionais, fechar a metade da conexão gRPC e aguardar quaisquer resultados adicionais até o servidor fechar a conexão gRPC.

AudioInConfig

Especifica como processar os dados do audio_in que serão fornecidos nas próximas solicitações. Para acessar as configurações recomendadas, consulte as práticas recomendadas do SDK do Google Assistente.

Campos
encoding

Encoding

Obrigatório Codificação de dados de áudio enviados em todas as mensagens audio_in.

sample_rate_hertz

int32

Obrigatório Taxa de amostragem (em Hertz) dos dados de áudio enviados em todas as mensagens audio_in. Os valores válidos vão de 16.000 a 24.000, mas 16.000 é o ideal. Para melhores resultados, defina a taxa de amostragem da fonte de áudio para 16.000 Hz. Se isso não for possível, use a taxa de amostragem nativa da fonte de áudio em vez de fazer nova amostragem.

Codificação

Codificação de áudio dos dados enviados na mensagem de áudio. O áudio precisa ser de um canal (mono).

Enums
ENCODING_UNSPECIFIED Não especificado. Retorna o resultado google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Amostras pouco elaboradas de 16 bits sem compactação (PCM Linear). Essa codificação não inclui cabeçalho, somente os bytes brutos de áudio.
FLAC FLAC (Free Lossless Audio Codec) é a codificação recomendada porque não tem perdas. Portanto, o reconhecimento não é comprometido e requer apenas cerca de metade da largura de banda do LINEAR16. Essa codificação inclui o cabeçalho de stream FLAC seguido pelos dados de áudio. Ele oferece suporte a amostras de 16 e 24 bits, mas nem todos os campos em STREAMINFO são compatíveis.

AudioOut

O áudio que contém a resposta do Google Assistente à consulta. Os blocos sequenciais de dados de áudio são recebidos em mensagens AssistResponse sequenciais.

Campos
audio_data

bytes

Somente saída: os dados de áudio que contêm a resposta do Google Assistente à consulta. Os blocos sequenciais de dados de áudio são recebidos em mensagens AssistResponse sequenciais.

AudioOutConfig

Especifica o formato desejado que o servidor usará quando retornar mensagens audio_out.

Campos
encoding

Encoding

Obrigatório A codificação dos dados de áudio a ser retornada em todas as mensagens audio_out.

sample_rate_hertz

int32

Obrigatório A taxa de amostragem em Hertz dos dados de áudio retornados em mensagens audio_out. Os valores válidos são: 16.000-24.000.

volume_percentage

int32

Obrigatório Configuração de volume atual da saída de áudio do dispositivo. Os valores válidos são de 1 a 100 (correspondente a 1% a 100%).

Codificação

Codificação dos dados retornados na mensagem de áudio. Todas as codificações são bytes de áudio brutos sem cabeçalho, exceto conforme indicado abaixo.

Enums
ENCODING_UNSPECIFIED Não especificado. Retorna o resultado google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Amostras pouco elaboradas de 16 bits sem compactação (PCM Linear).
MP3 Codificação de áudio MP3. A taxa de amostragem é codificada no payload.
OPUS_IN_OGG Áudio codificado em Opus unido em um contêiner ogg. O resultado será um arquivo que pode ser reproduzido de forma nativa no Android e em alguns navegadores, como o Chrome. A qualidade da codificação é consideravelmente maior do que a do MP3 e usa a mesma taxa de bits. A taxa de amostragem é codificada no payload.

DebugConfig

Parâmetros de depuração para a solicitação atual.

Campos
return_debug_info

bool

Quando esse campo é definido como verdadeiro, o campo debug_info em AssistResponse pode ser preenchido. No entanto, isso vai aumentar significativamente a latência das respostas.

DebugInfo

Informações de depuração para o desenvolvedor. Retornará somente se a solicitação definir return_debug_info como "true".

Campos
aog_agent_to_assistant_json

string

A resposta JSON original de um agente do Action-on-Google para o servidor do Google. Consulte AppResponse. Ele só será preenchido se o criador da solicitação for proprietário do projeto AoG e se ele estiver no modo de visualização.

DeviceAction

A resposta retornada ao dispositivo se o usuário tiver acionado uma ação do dispositivo. Por exemplo, um dispositivo compatível com a consulta Turn on the light receberia um DeviceAction com um payload JSON que contém a semântica da solicitação.

Campos
device_request_json

string

JSON que contém a resposta ao comando do dispositivo gerada com base na gramática de ações do dispositivo acionadas. O formato é fornecido pela intent action.devices.EXECUTE para uma determinada característica.

DeviceConfig

Campos obrigatórios que identificam o dispositivo para o Google Assistente.

Consulte também:

Campos
device_id

string

Obrigatório Identificador exclusivo do dispositivo. O ID precisa ter até 128 caracteres. Exemplo: DBCDW098234. Ele PRECISA corresponder ao device_id retornado do registro do dispositivo. Esse device_id é usado para corresponder aos dispositivos registrados do usuário e pesquisar as características e os recursos compatíveis com o dispositivo. Essas informações não devem mudar após a reinicialização do dispositivo. No entanto, ele não deve ser salvo após as redefinições para a configuração original.

device_model_id

string

Obrigatório Identificador exclusivo do modelo do dispositivo. A combinação de device_model_id e device_id precisa ter sido associada anteriormente ao registro do dispositivo.

DeviceLocation

Existem três origens de locais. Eles são usados com esta precedência:

  1. Esse DeviceLocation, que é usado principalmente para dispositivos móveis com GPS .
  2. Local especificado pelo usuário durante a configuração do dispositivo, por usuário e por dispositivo. Esse local será usado se DeviceLocation não for especificado.
  3. Local inferido com base no endereço IP. Isso será usado somente se nenhuma das opções acima for especificada.
Campos
coordinates

LatLng

Latitude e longitude do dispositivo.

DialogStateIn

Fornece informações sobre o estado atual da caixa de diálogo.

Campos
conversation_state

bytes

Obrigatório Esse campo sempre precisa ser definido como o valor DialogStateOut.conversation_state retornado na RPC Assist anterior. Ele só deve ser omitido (campo não definido) se não houver RPC Assist anterior, porque essa é a primeira RPC Assist feita por este dispositivo após a primeira configuração e/ou uma redefinição para a configuração original.

language_code

string

Obrigatório Idioma da solicitação na sintaxe IETF BCP 47 (por exemplo, "en-US"). Consulte Suporte a idiomas para mais informações. Se você tiver selecionado um idioma para o device_id usando o menu Configurações do app Google Assistente do smartphone, essa seleção vai substituir o valor.

device_location

DeviceLocation

Opcional: local do dispositivo em que a consulta foi originada.

is_new_conversation

bool

Opcional: se verdadeiro, o servidor vai tratar a solicitação como uma nova conversa e não usar o estado da solicitação anterior. Defina este campo como verdadeiro quando a conversa precisar ser reiniciada, por exemplo, após a reinicialização do dispositivo ou após um intervalo de tempo significativo desde a consulta anterior.

DialogStateOut

O estado da caixa de diálogo resultante da consulta do usuário. Várias destas mensagens podem ser recebidas.

Campos
supplemental_display_text

string

Somente saída Texto de exibição complementar do Google Assistente. Pode ser a mesma fala falada em AssistResponse.audio_out ou algumas informações adicionais que ajudam o entendimento do usuário.

conversation_state

bytes

Informações de estado somente saída para a RPC Assist subsequente. Esse valor precisa ser salvo no cliente e retornado no campo DialogStateIn.conversation_state com a próxima RPC Assist. O cliente não precisa interpretar nem usar esse valor. Essas informações devem ser salvas após a reinicialização do dispositivo. No entanto, esse valor precisa ser apagado (não salvo no cliente) durante uma redefinição para a configuração original.

microphone_mode

MicrophoneMode

Somente saída Especifica o modo do microfone depois que essa RPC Assist é processada.

volume_percentage

int32

Somente saída nível de volume atualizado. O valor será 0 ou omitido (indicando nenhuma mudança), a menos que um comando de voz como Aumentar o volume ou Definir nível de volume 4 seja reconhecido. Nesse caso, o valor vai estar entre 1 e 100 (correspondente ao novo nível de volume de 1% a 100%). Normalmente, um cliente precisa usar esse nível de volume ao reproduzir os dados do audio_out, manter esse valor como o nível de volume atual e fornecê-lo no AudioOutConfig do próximo AssistRequest. Alguns clientes também podem implementar outras maneiras de permitir que o nível de volume atual seja alterado, por exemplo, fornecendo um botão em que o usuário pode girar.

MicrophoneMode

Estados possíveis do microfone após a conclusão de uma RPC Assist.

Enums
MICROPHONE_MODE_UNSPECIFIED Nenhum modo especificado.
CLOSE_MICROPHONE O serviço não espera uma pergunta seguinte do usuário. O microfone precisa permanecer desativado até ser reativado.
DIALOG_FOLLOW_ON O serviço espera uma pergunta complementar do usuário. O microfone precisa ser aberto novamente quando a reprodução de AudioOut for concluída, iniciando uma nova chamada de RPC Assist para enviar o novo áudio.

ScreenOut

A resposta da saída visual do Google Assistente à consulta. Ativado por screen_out_config.

Campos
format

Format

Somente saída Formato dos dados da tela fornecidos.

data

bytes

Somente saída: os dados brutos da tela a serem mostrados como resultado da consulta do Google Assistente.

Formato

Formatos possíveis dos dados da tela.

Enums
FORMAT_UNSPECIFIED Nenhum formato especificado.
HTML Os dados contêm um layout HTML5 completo codificado em UTF-8, por exemplo, <html><body><div>...</div></body></html>. Ele precisa ser renderizado junto com a resposta de áudio. O doctype HTML5 precisa ser incluído nos dados HTML reais.

ScreenOutConfig

Especifica o formato desejado para o servidor usar quando ele retornar uma resposta screen_out.

Campos
screen_mode

ScreenMode

Modo de tela visual atual do dispositivo durante a emissão da consulta.

ScreenMode

Modos possíveis para saída visual da tela no dispositivo.

Enums
SCREEN_MODE_UNSPECIFIED Nenhum modo de vídeo especificado. O Google Assistente pode responder como se estivesse no modo OFF.
OFF A tela está desligada (ou tem o brilho ou outras configurações tão baixas que não são visíveis). O Google Assistente normalmente não retorna uma resposta de tela nesse modo.
PLAYING Nesse modo, o Google Assistente normalmente retorna uma resposta de tela parcial.

SpeechRecognitionResult

A transcrição estimada de uma frase que o usuário falou. Pode ser um único segmento ou o palpite completo da consulta falada do usuário.

Campos
transcript

string

Somente saída Texto de transcrição que representa as palavras que o usuário falou.

stability

float

Somente saída: estimativa da probabilidade de o Google Assistente não mudar o palpite sobre esse resultado. Os valores variam de 0,0 (completamente instável) a 1,0 (completamente estável e final). O padrão de 0,0 é um valor de sentinela indicando que stability não foi definido.