Package google.assistant.embedded.v1alpha2

Índice

EmbeddedAssistant

Servicio que implementa la API de Asistente de Google

Asistencia

rpc Assist(AssistRequest) returns (AssistResponse)

Inicia o continúa una conversación con el servicio de Asistente incorporado. Cada llamada realiza un recorrido de ida y vuelta; envía una solicitud de audio al servicio y recibe la respuesta de audio. Usa una transmisión bidireccional para recibir resultados, como el evento END_OF_UTTERANCE, mientras envía audio.

Una conversación es una o más conexiones gRPC, cada una de las cuales consta de varias solicitudes y respuestas transmitidas. Por ejemplo, el usuario dice Agregar a mi lista de compras y Asistente responde ¿Qué quieres agregar?. La secuencia de solicitudes y respuestas transmitidas en el primer mensaje de gRPC podría ser la siguiente:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript "agregar a la lista de compras"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

Luego, el usuario dice bagels y Asistente responde: "De acuerdo, agregué bagels" a tu lista de compras. Esto se envía como otra llamada de conexión de gRPC al método Assist, nuevamente con solicitudes y respuestas transmitidas, como las siguientes:

  • 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

Aunque no se garantiza el orden preciso de las respuestas, los mensajes AssistResponse.audio_out secuenciales siempre contendrán porciones secuenciales de audio.

Alcances de la autorización

Requiere el siguiente alcance de OAuth:

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

Para obtener más información, consulta la Guía de Auth.

AssistConfig

Especifica cómo procesar los mensajes AssistRequest.

Campos
audio_out_config

AudioOutConfig

Obligatorio: Especifica cómo dar formato al audio que se mostrará.

screen_out_config

ScreenOutConfig

Opcional: Especifica el formato deseado que se usará cuando el servidor muestre una respuesta visual de la pantalla.

dialog_state_in

DialogStateIn

Obligatorio Representa el estado actual del diálogo.

device_config

DeviceConfig

Configuración del dispositivo que identifica de forma exclusiva un dispositivo específico.

debug_config

DebugConfig

Opcional: Parámetros de depuración para toda la RPC de Assist

Campo de unión type.

type puede ser una de las siguientes opciones:
audio_in_config

AudioInConfig

Especifica cómo procesar el audio entrante posterior. Obligatorio si se proporcionarán AssistRequest.audio_in bytes en solicitudes posteriores.

text_query

string

Es la entrada de texto que se enviará a Asistente. Se puede propagar desde una interfaz de texto si la entrada de audio no está disponible.

AssistRequest

El mensaje de nivel superior que envía el cliente. Los clientes deben enviar, al menos, dos mensajes de AssistRequest, aunque suelen ser varios. El primer mensaje debe contener un mensaje config y no debe contener datos audio_in. Todos los mensajes posteriores deben contener datos audio_in y no deben contener un mensaje config.

Campos
Campo de unión type. Se debe especificar exactamente uno de estos campos en cada AssistRequest. type puede ser solo uno de los siguientes:
config

AssistConfig

El mensaje config proporciona información al reconocedor que especifica cómo procesar la solicitud. El primer mensaje AssistRequest debe contener un mensaje config.

audio_in

bytes

Los datos de audio que se reconocerán. Los fragmentos secuenciales de datos de audio se envían en mensajes AssistRequest secuenciales. El primer mensaje AssistRequest no debe contener datos audio_in, pero todos los mensajes AssistRequest posteriores deben contener datos audio_in. Los bytes de audio deben estar codificados como se especifica en AudioInConfig. El audio debe enviarse aproximadamente en tiempo real (16,000 muestras por segundo). Se mostrará un error si el audio se envía mucho más rápido o lento.

AssistResponse

El mensaje de nivel superior que recibe el cliente. Se transmite una serie de uno o más mensajes AssistResponse al cliente.

Campos
event_type

EventType

Solo salida indica el tipo de evento.

audio_out

AudioOut

Solo salida: Es el audio que contiene la respuesta del Asistente a la consulta.

screen_out

ScreenOut

Solo salida: Contiene la respuesta visual del Asistente a la consulta.

device_action

DeviceAction

Solo salida: Contiene la acción activada por la consulta con las cargas útiles adecuadas y el análisis semántico.

speech_results[]

SpeechRecognitionResult

Solo salida: Esta lista repetida contiene cero o más resultados de reconocimiento de voz que corresponden a partes consecutivas del audio que se está procesando, comenzando por la parte que corresponde al audio más antiguo (y la más estable) a la parte que corresponde al audio más reciente. Las cadenas se pueden concatenar para ver la respuesta completa en curso. Cuando se complete el reconocimiento de voz, la lista contendrá un elemento con stability de 1.0.

dialog_state_out

DialogStateOut

Solo salida: Contiene un resultado relacionado con la consulta del usuario.

debug_info

DebugInfo

Información de depuración de solo salida para el desarrollador. Solo se muestra si la solicitud configuró return_debug_info como verdadero.

EventType

Indica el tipo de evento.

Enumeradores
EVENT_TYPE_UNSPECIFIED No se especificó ningún evento.
END_OF_UTTERANCE Este evento indica que el servidor detectó el final del enunciado de voz del usuario y que no espera que siga hablando. Por lo tanto, el servidor no procesará audio adicional (aunque puede que muestre resultados adicionales de forma posterior). El cliente debe dejar de enviar datos de audio adicionales, cerrar de forma parcial la conexión de gRPC y esperar cualquier resultado adicional hasta que el servidor también la cierre.

AudioInConfig

Especifica cómo procesar los datos de audio_in que se proporcionarán en solicitudes posteriores. Para ver las opciones de configuración recomendadas, consulta las prácticas recomendadas del SDK de Asistente de Google.

Campos
encoding

Encoding

Obligatorio: Es la codificación de los datos de audio enviados en todos los mensajes audio_in.

sample_rate_hertz

int32

Obligatorio: Es la tasa de muestreo (en hercios) de los datos de audio enviados en todos los mensajes de audio_in. Los valores válidos van de 16,000 a 24,000, pero 16,000 es el valor óptimo. Para obtener los mejores resultados, establece la tasa de muestreo de la fuente de audio en 16,000 Hz. Si esto no es posible, usa la tasa de muestreo nativa de la fuente de audio (en lugar de volver a muestrear).

Codificación

Es la codificación de audio de los datos enviados en el mensaje de audio. El audio debe ser de un canal (mono).

Enumeradores
ENCODING_UNSPECIFIED No se especifica. Se mostrará el resultado google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Son las muestras de little-endian de 16 bits firmadas y sin comprimir (PCM lineal). Esta codificación no incluye encabezado, solo los bytes de audio sin procesar.
FLAC FLAC (códec de audio sin pérdida gratuito) es la codificación recomendada porque no tiene pérdidas (por lo tanto, el reconocimiento no se ve comprometido) y requiere solo la mitad del ancho de banda de LINEAR16. Esta codificación incluye el encabezado de la transmisión FLAC seguido de los datos de audio. Admite muestras de 16 y 24 bits. Sin embargo, no todos los campos de STREAMINFO son compatibles.

AudioOut

Es el audio que contiene la respuesta de Asistente a la consulta. Se reciben fragmentos secuenciales de datos de audio en mensajes AssistResponse secuenciales.

Campos
audio_data

bytes

Solo salida: Los datos de audio que contienen la respuesta del Asistente a la consulta. Se reciben fragmentos secuenciales de datos de audio en mensajes AssistResponse secuenciales.

AudioOutConfig

Especifica el formato que debe usar el servidor cuando muestre mensajes audio_out.

Campos
encoding

Encoding

Obligatorio La codificación de los datos de audio que se mostrará en todos los mensajes audio_out.

sample_rate_hertz

int32

Obligatorio: Es la tasa de muestreo en hercios de los datos de audio que se muestran en los mensajes audio_out. Los valores válidos son 16,000-24,000.

volume_percentage

int32

Obligatorio: Es la configuración del volumen actual de la salida de audio del dispositivo. Los valores válidos van del 1 al 100 (corresponde al 1% al 100%).

Codificación

Es la codificación de audio de los datos mostrados en el mensaje de audio. Todas las codificaciones son bytes de audio sin procesar y sin encabezado, excepto como se indica a continuación.

Enumeradores
ENCODING_UNSPECIFIED No se especifica. Se mostrará el resultado google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Son las muestras de little-endian de 16 bits firmadas y sin comprimir (PCM lineal).
MP3 con codificación de audio MP3. La tasa de muestreo está codificada en la carga útil.
OPUS_IN_OGG Audio codificado en Opus que se une a un contenedor ogg. El resultado será un archivo que se puede reproducir de forma nativa en Android y en algunos navegadores (como Chrome). La calidad de la codificación es considerablemente mayor que la de MP3, pero con la misma tasa de bits. La tasa de muestreo está codificada en la carga útil.

DebugConfig

Parámetros de depuración para la solicitud actual

Campos
return_debug_info

bool

Cuando este campo se establece como verdadero, se puede propagar el campo debug_info en AssistResponse. Sin embargo, aumentará significativamente la latencia de las respuestas.

DebugInfo

Información de depuración para el desarrollador Solo se muestra si la solicitud configuró return_debug_info como verdadero.

Campos
aog_agent_to_assistant_json

string

La respuesta JSON original de un agente de Action-on-Google al servidor de Google. Consulta AppResponse. Solo se propagará si el creador de la solicitud es propietario del proyecto de AoG y este se encuentra en modo de vista previa.

DeviceAction

Es la respuesta que se muestra al dispositivo si el usuario activó una Acción del dispositivo. Por ejemplo, un dispositivo que admita la consulta Turn on the light recibirá un DeviceAction con una carga útil de JSON que contendrá la semántica de la solicitud.

Campos
device_request_json

string

JSON que contiene la respuesta de comando del dispositivo generada a partir de la gramática de la acción del dispositivo activada. El intent action.devices.EXECUTE proporciona el formato para una trait determinada.

DeviceConfig

Obligatorios Son los campos que permiten al Asistente identificar el dispositivo.

Consulta lo siguiente:

Campos
device_id

string

Obligatorio: Es el identificador único del dispositivo. El ID debe tener 128 caracteres o menos. Ejemplo: DBCDW098234. Este DEBE coincidir con el device_id devuelto por el registro del dispositivo. Este device_id se usa para buscar coincidencias con los dispositivos registrados del usuario a fin de buscar las características y capacidades compatibles de este dispositivo. Esta información no debería cambiar después de cada reinicio del dispositivo. Sin embargo, no se debe guardar después de restablecer la configuración de fábrica.

device_model_id

string

Obligatorio: Es el identificador único del modelo de dispositivo. La combinación de device_model_id y device_id se debe haber asociado previamente a través del registro del dispositivo.

DeviceLocation

Hay tres fuentes de ubicaciones. Se usan con la siguiente prioridad:

  1. Este DeviceLocation, que se usa principalmente para dispositivos móviles con GPS .
  2. Ubicación especificada por el usuario durante la configuración del dispositivo (es por usuario y por dispositivo). Esta ubicación se usa si no se especifica DeviceLocation.
  3. Ubicación inferida basada en la dirección IP. Solo se usa si no se especifica ninguna de las opciones anteriores.
Campos
coordinates

LatLng

Latitud y longitud del dispositivo

DialogStateIn

Proporciona información sobre el estado del diálogo actual.

Campos
conversation_state

bytes

Obligatorio: Este campo siempre debe establecerse en el valor DialogStateOut.conversation_state que se mostró en la RPC de Assist anterior. Solo se debe omitir (campo no establecido) si no hubo ninguna RPC de Assist anterior, ya que esta es la primera RPC de Assist que realiza este dispositivo después de que se configuró por primera vez o del restablecimiento de la configuración de fábrica.

language_code

string

Obligatorio: Es el idioma de la solicitud en la sintaxis IETF BCP 47 (por ejemplo, "en-US"). Consulta Idiomas compatibles para obtener más información. Si seleccionaste un idioma para este device_id en el menú Configuración de la app del Asistente de Google del teléfono, esa selección anulará este valor.

device_location

DeviceLocation

Opcional: Es la ubicación del dispositivo donde se originó la consulta.

is_new_conversation

bool

Opcional: Si es verdadero, el servidor considerará la solicitud como una conversación nueva y no usará el estado de la solicitud anterior. Establece este campo en verdadero cuando se deba reiniciar la conversación, por ejemplo, después de reiniciar un dispositivo o después de un tiempo significativo desde la consulta anterior.

DialogStateOut

El estado del diálogo que resulta de la consulta del usuario. Es posible que se reciban varios de estos mensajes.

Campos
supplemental_display_text

string

Solo salida: Texto de visualización complementario del Asistente. Puede ser igual al discurso que se pronuncia en AssistResponse.audio_out o podría ser información adicional que ayude a la comprensión del usuario.

conversation_state

bytes

Información de estado solo de salida para la RPC Assist posterior. Este valor debe guardarse en el cliente y mostrarse en el campo DialogStateIn.conversation_state con la siguiente RPC de Assist. (El cliente no necesita interpretar ni usar este valor). Esta información debe guardarse después de reiniciar el dispositivo. Sin embargo, este valor se debe borrar (no se debe guardar en el cliente) durante un restablecimiento de la configuración predeterminada de fábrica.

microphone_mode

MicrophoneMode

Solo salida: Especifica el modo del micrófono después de que se procese esta RPC de Assist.

volume_percentage

int32

Solo salida: Se actualizó el nivel del volumen. El valor será 0 o se omitirá (lo que indica que no hay cambios), a menos que se reconozca un comando por voz como Sube el volumen o Establecer el volumen en el nivel 4, en cuyo caso el valor será entre 1 y 100 (correspondiente al nuevo nivel de volumen de 1% a 100%). Por lo general, el cliente debe usar este nivel de volumen cuando reproduce los datos de audio_out, conservar este valor como el nivel de volumen actual y proporcionarlo en el AudioOutConfig de la siguiente AssistRequest. (Algunos clientes también pueden implementar otras formas de permitir que se cambie el nivel actual del volumen, por ejemplo, proporcionando un botón que el usuario pueda girar).

MicrophoneMode

Estados posibles del micrófono después de que se completa una RPC Assist.

Enumeradores
MICROPHONE_MODE_UNSPECIFIED No se especificó ningún modo.
CLOSE_MICROPHONE El servicio no espera una pregunta de seguimiento del usuario. El micrófono debe permanecer apagado hasta que el usuario lo reactive.
DIALOG_FOLLOW_ON El servicio espera una pregunta de seguimiento del usuario. El micrófono se debe volver a abrir cuando se complete la reproducción de AudioOut (iniciando una nueva llamada RPC de Assist para enviar el audio nuevo).

ScreenOut

Es la salida visual de respuesta a la consulta de Asistente. Habilitada por screen_out_config.

Campos
format

Format

Solo salida: Es el formato de los datos de la pantalla proporcionados.

data

bytes

Solo salida Son los datos sin procesar de la pantalla que se mostrarán como resultado de una consulta al Asistente.

Formato

Posibles formatos de los datos de la pantalla.

Enumeradores
FORMAT_UNSPECIFIED No se especificó ningún formato.
HTML Los datos contendrán un diseño HTML5 totalmente codificado en UTF-8, p.ej., <html><body><div>...</div></body></html>. Está diseñado para procesarse junto con la respuesta de audio. Ten en cuenta que el DOCTYPE de HTML5 debe incluirse en los datos HTML reales.

ScreenOutConfig

Especifica el formato que debe usar el servidor cuando muestre una respuesta screen_out.

Campos
screen_mode

ScreenMode

Es el modo de pantalla visual actual para el dispositivo mientras se emite la consulta.

ScreenMode

Modos posibles de salida de pantalla en el dispositivo.

Enumeradores
SCREEN_MODE_UNSPECIFIED No se especificó ningún modo de video. Es posible que Asistente responda como si estuviera en el modo OFF.
OFF La pantalla está apagada (o tiene el brillo o algún otro parámetro de configuración tan bajo que no se puede ver). Por lo general, en este modo, el Asistente no muestra una respuesta en pantalla.
PLAYING Por lo general, en este modo, el Asistente muestra una respuesta en pantalla parcial.

SpeechRecognitionResult

La transcripción estimada de una frase que el usuario ha pronunciado. Puede ser un solo segmento o la consulta completa de la consulta por voz del usuario.

Campos
transcript

string

Solo salida: Texto de transcripción que representa las palabras que dijo el usuario.

stability

float

Solo salida: Es una estimación de la probabilidad de que Asistente no cambie su suposición sobre este resultado. Los valores varían de 0.0 (completamente inestable) a 1.0 (completamente estable y final). El valor predeterminado de 0.0 es un valor centinela que indica que no se estableció stability.