Package google.assistant.embedded.v1alpha2

Индекс

Встроенный помощник

Сервис, реализующий API Google Assistant.

Помощь

rpc Assist( AssistRequest ) returns ( AssistResponse )

Инициирует или продолжает разговор со встроенной службой помощника. Каждый вызов выполняет один круговой обход, отправляя звуковой запрос в службу и получая звуковой ответ. Использует двунаправленную потоковую передачу для получения результатов, таких как событие END_OF_UTTERANCE , при отправке аудио.

Разговор — это одно или несколько соединений gRPC, каждое из которых состоит из нескольких потоковых запросов и ответов. Например, пользователь говорит «Добавить в мой список покупок» , а Ассистент отвечает : «Что вы хотите добавить?» . Последовательность потоковых запросов и ответов в первом сообщении 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

Затем пользователь говорит «бублики» , и Ассистент отвечает : «ОК, я добавил бублики в ваш список покупок» . Это отправляется как еще один вызов соединения 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

Текстовый ввод, который будет отправлен Ассистенту. Его можно заполнить из текстового интерфейса, если аудиовход недоступен.

Запрос помощи

Сообщение верхнего уровня, отправленное клиентом. Клиенты должны отправить как минимум два, а обычно множество сообщений 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 пересылается обратно клиенту.

Поля
event_type

EventType

Только вывод Указывает тип события.

audio_out

AudioOut

Только вывод Аудио, содержащее ответ Ассистента на запрос.

screen_out

ScreenOut

Только вывод Содержит визуальный ответ Ассистента на запрос.

device_action

DeviceAction

Только вывод. Содержит действие, инициируемое запросом, с соответствующими полезными данными и семантическим анализом.

speech_results[]

SpeechRecognitionResult

Только для вывода Этот повторяющийся список содержит ноль или более результатов распознавания речи, которые соответствуют последовательным частям аудио, обрабатываемым в данный момент, начиная с части, соответствующей самому раннему аудио (и наиболее стабильной части), до части, соответствующей самому последнему аудио. Строки можно объединить для просмотра полного ответа в процессе выполнения. Когда распознавание речи завершится, этот список будет содержать один элемент со stability 1.0 .

dialog_state_out

DialogStateOut

Только вывод Содержит выходные данные, относящиеся к запросу пользователя.

debug_info

DebugInfo

Только вывод. Отладочная информация для разработчика. Возвращается только в том случае, если в запросе return_debug_info установлено значение true.

Тип события

Указывает тип события.

Перечисления
EVENT_TYPE_UNSPECIFIED Событие не указано.
END_OF_UTTERANCE Это событие указывает на то, что сервер обнаружил окончание речевого высказывания пользователя и не ожидает дополнительной речи. Поэтому сервер не будет обрабатывать дополнительный звук (хотя впоследствии может вернуть дополнительные результаты). Клиенту следует прекратить отправку дополнительных аудиоданных, наполовину закрыть соединение gRPC и дождаться дополнительных результатов, пока сервер не закроет соединение gRPC.

Аудиоинконфиг

Указывает, как обрабатывать данные audio_in , которые будут предоставлены в последующих запросах. Рекомендуемые настройки см. в рекомендациях по Google Assistant SDK.

Поля
encoding

Encoding

Обязательное Кодирование аудиоданных, отправляемых во всех сообщениях audio_in .

sample_rate_hertz

int32

Требуемая частота дискретизации (в герцах) аудиоданных, отправляемых во всех сообщениях audio_in . Допустимые значения: 16000–24000, но оптимальное значение — 16000. Для достижения наилучших результатов установите частоту дискретизации источника звука на 16 000 Гц. Если это невозможно, используйте собственную частоту дискретизации источника звука (вместо повторной выборки).

Кодирование

Аудиокодирование данных, передаваемых в аудиосообщении. Звук должен быть одноканальным (моно).

Перечисления
ENCODING_UNSPECIFIED Не указан. Вернет результат google.rpc.Code.INVALID_ARGUMENT .
LINEAR16 Несжатые 16-битные образцы с прямым порядком байтов (Linear PCM). Эта кодировка не включает заголовок, а только необработанные аудиобайты.
FLAC FLAC (бесплатный аудиокодек без потерь) — рекомендуемая кодировка, поскольку она не имеет потерь (поэтому распознавание не подвергается риску) и требует лишь примерно половины пропускной способности LINEAR16 . Эта кодировка включает заголовок потока FLAC , за которым следуют аудиоданные. Он поддерживает 16-битные и 24-битные выборки, однако не все поля в STREAMINFO поддерживаются.

Аудио выход

Звук, содержащий ответ Ассистента на запрос. Последовательные фрагменты аудиоданных принимаются в последовательных сообщениях AssistResponse .

Поля
audio_data

bytes

Только для вывода Аудиоданные, содержащие ответ Ассистента на запрос. Последовательные фрагменты аудиоданных принимаются в последовательных сообщениях AssistResponse .

АудиоВыходКонфиг

Указывает желаемый формат, который сервер будет использовать при возврате сообщений 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-битные образцы с прямым порядком байтов (Linear PCM).
MP3 Кодирование звука в формате MP3. Частота дискретизации закодирована в полезных данных.
OPUS_IN_OGG Звук в кодировке Opus, завернутый в контейнер ogg. Результатом будет файл, который можно будет воспроизводить на Android и в некоторых браузерах (например, Chrome). Качество кодирования значительно выше, чем у MP3 при использовании того же битрейта. Частота дискретизации закодирована в полезных данных.

Отладочная конфигурация

Параметры отладки для текущего запроса.

Поля
return_debug_info

bool

Если для этого поля установлено значение true, поле debug_info в AssistResponse может быть заполнено. Однако это существенно увеличит задержку ответов.

Отладочная информация

Отладочная информация для разработчика. Возвращается только в том случае, если в запросе return_debug_info установлено значение true.

Поля
aog_agent_to_assistant_json

string

Исходный ответ JSON от агента Action-on-Google на сервер Google. См. AppResponse . Он будет заполнен только в том случае, если создатель запроса владеет проектом AoG и проект AoG находится в режиме предварительного просмотра.

УстройствоДействие

Ответ возвращается на устройство, если пользователь инициировал действие устройства. Например, устройство, поддерживающее запрос « Включи свет», получит DeviceAction с полезными данными JSON, содержащими семантику запроса.

Поля
device_request_json

string

JSON, содержащий ответ на команду устройства, созданный на основе грамматики триггерного действия устройства. Формат задается намерением action.devices.EXECUTE для данного типажа .

Конфигурация устройства

Обязательные поля, которые идентифицируют устройство для Ассистента.

Смотрите также:

Поля
device_id

string

Обязательный уникальный идентификатор устройства. Длина идентификатора не должна превышать 128 символов. Пример: DBCDW098234. Он ДОЛЖЕН соответствовать идентификатору устройства, полученному при регистрации устройства. Этот идентификатор устройства используется для сопоставления с зарегистрированными устройствами пользователя для поиска поддерживаемых характеристик и возможностей этого устройства. Эта информация не должна меняться при перезагрузке устройства. Однако его не следует сохранять при сбросе настроек к заводским настройкам.

device_model_id

string

Обязательный уникальный идентификатор модели устройства. Комбинация device_model_id и device_id должна быть ранее связана при регистрации устройства.

Расположение устройства

Есть три источника локаций. Они используются со следующим приоритетом:

  1. Это DeviceLocation , которое в основном используется для мобильных устройств с GPS.
  2. Местоположение, указанное пользователем при настройке устройства; это для каждого пользователя, для каждого устройства. Это расположение используется, если DeviceLocation не указано.
  3. Предполагаемое местоположение на основе IP-адреса. Используется только в том случае, если не указано ни одно из вышеперечисленных.
Поля
coordinates

LatLng

Широта и долгота устройства.

Диалогстатеин

Предоставляет информацию о текущем состоянии диалога.

Поля
conversation_state

bytes

Обязательное значение. В этом поле всегда должно быть установлено значение DialogStateOut.conversation_state , которое было возвращено в предыдущем RPC Assist . Его следует опустить (поле не задано), только если предшествующий Assist RPC не выполнялся, поскольку это первый Assist RPC, выполненный данным устройством после его первой настройки и/или сброса к заводским настройкам.

language_code

string

Требуемый язык запроса в синтаксисе IETF BCP 47 (например, «en-US»). Дополнительную информацию см. в разделе Языковая поддержка . Если вы выбрали язык для этого device_id с помощью меню «Настройки» в приложении Google Assistant вашего телефона, этот выбор переопределит это значение.

device_location

DeviceLocation

Необязательное расположение устройства, на котором возник запрос.

is_new_conversation

bool

Необязательно. Если значение равно true, сервер будет рассматривать запрос как новый диалог и не будет использовать состояние предыдущего запроса. Установите для этого поля значение true, если диалог необходимо возобновить, например, после перезагрузки устройства или по прошествии значительного времени с момента предыдущего запроса.

Диалогстатеаут

Состояние диалога, полученное в результате запроса пользователя. Может быть получено несколько таких сообщений.

Поля
supplemental_display_text

string

Только вывод. Дополнительный текст, отображаемый помощником. Это может быть то же самое, что речь, произнесенная в 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 , сохранять это значение в качестве текущего уровня громкости и указывать его в AudioOutConfig следующего AssistRequest . (Некоторые клиенты могут также реализовать другие способы изменения текущего уровня громкости, например, путем предоставления ручки, которую пользователь может повернуть.)

Режим микрофона

Возможные состояния микрофона после завершения Assist RPC.

Перечисления
MICROPHONE_MODE_UNSPECIFIED Режим не указан.
CLOSE_MICROPHONE Сервис не ожидает дополнительного вопроса от пользователя. Микрофон должен оставаться выключенным до тех пор, пока пользователь не активирует его повторно.
DIALOG_FOLLOW_ON Служба ожидает ответного вопроса от пользователя. Микрофон следует снова открыть после завершения воспроизведения AudioOut (путем запуска нового вызова Assist RPC для отправки нового звука).

Исключать

Визуальный ответ Ассистента на запрос. Включено screen_out_config .

Поля
format

Format

Только вывод Формат предоставляемых экранных данных.

data

bytes

Только вывод. Необработанные данные экрана, которые будут отображаться в результате запроса Ассистента.

Формат

Возможные форматы данных экрана.

Перечисления
FORMAT_UNSPECIFIED Формат не указан.
HTML Данные будут содержать полностью сформированный макет HTML5 в кодировке UTF-8, например <html><body><div>...</div></body></html> . Он предназначен для рендеринга вместе со звуковым ответом. Обратите внимание, что тип документа HTML5 должен быть включен в фактические данные HTML.

Скринаутконфиг

Указывает желаемый формат, который сервер будет использовать при возврате ответа screen_out .

Поля
screen_mode

ScreenMode

Текущий визуальный режим экрана устройства при отправке запроса.

Режим экрана

Возможные режимы визуального вывода на экран устройства.

Перечисления
SCREEN_MODE_UNSPECIFIED Видеорежим не указан. Ассистент может реагировать так, как будто он находится в OFF режиме.
OFF Экран выключен (или его яркость или другие настройки настолько низкие, что их не видно). В этом режиме Ассистент обычно не отвечает на экран.
PLAYING В этом режиме Ассистент обычно возвращает частичный ответ на экране.

Распознавание речиРезультат

Предполагаемая транскрипция фразы, произнесенной пользователем. Это может быть отдельный сегмент или полная версия устного запроса пользователя.

Поля
transcript

string

Текст стенограммы , предназначенный только для вывода, представляющий слова, произнесенные пользователем.

stability

float

Только вывод Оценка вероятности того, что Помощник не изменит свое предположение об этом результате. Значения варьируются от 0,0 (полностью нестабильно) до 1,0 (полностью стабильно и окончательно). Значение по умолчанию 0,0 — это контрольное значение, указывающее, stability не была установлена.