Package google.assistant.embedded.v1alpha2

索引

EmbeddedAssistant

实现 Google Assistant 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 助理会回复“好的，我已将百吉饼添加到你的购物清单中”。这将作为另一个 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

如需了解详情，请参阅身份验证指南。

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 中所述对音频字节进行编码。音频必须以近乎实时的速度发送（每秒 16000 个样本）。如果音频发送速度明显变快或变慢，系统将会返回错误。

AssistResponse

客户端收到的顶级消息。将一系列一个或多个 AssistResponse 消息流式传输回客户端。

字段
event_type

EventType

仅限输出：表示事件类型。

audio_out

AudioOut

仅限输出：包含 Google 助理对询问的回复的音频。
screen_out

ScreenOut

仅限输出：包含 Google 助理对查询的视觉响应。

device_action

DeviceAction

仅限输出：包含由具有适当载荷和语义解析的查询触发的操作。

speech_results[]

SpeechRecognitionResult

仅限输出：此重复列表包含零个或多个语音识别结果，这些结果对应于当前正在处理的音频的连续部分，从与最早音频（和最稳定部分）对应的部分开始，到与最新音频对应的部分开始。您可以串联这些字符串，以查看处理中的完整响应。语音识别完成后，此列表将包含一个 stability 为 1.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 Assistant SDK 最佳实践。

字段
encoding

Encoding

必需：对所有 audio_in 消息中发送的音频数据的编码。

sample_rate_hertz

int32

必需：所有 audio_in 消息中发送的音频数据的采样率（以赫兹为单位）。有效值为 16000-24000，但最佳值为 16000。为获得最佳结果，请将音频源的采样率设置为 16000 Hz。如果无法做到这一点，请使用音频源的原生采样率（而不是重新采样）。

编码

语音消息中发送的数据的音频编码。音频必须为单声道（单声道）。

枚举
ENCODING_UNSPECIFIED 未指定。将返回结果 google.rpc.Code.INVALID_ARGUMENT。
LINEAR16 未压缩的 16 位有符号小端字节序采样（线性 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

如果用户已触发设备操作，则返回设备响应。例如，支持查询“开灯”的设备会收到 DeviceAction，其中包含包含请求语义的 JSON 载荷。

字段
device_request_json

string

JSON，其中包含从触发的设备操作语法生成的设备命令响应。格式由 action.devices.EXECUTE intent 针对给定的特征指定。

DeviceConfig

必需字段，用于向 Google 助理标识设备。

另请参阅：

字段
device_id

string

必需的设备唯一标识符。ID 长度不得超过 128 个字符。示例：DBCDW098234。此 ID 必须与设备注册时返回的 device_id 一致。此 device_id 用于匹配用户的已注册设备，以查找此设备支持的特征和功能。设备重启后，此信息应该不会发生变化。不过，在恢复出厂设置后不应保存该名称。

device_model_id

string

必需：设备型号的唯一标识符。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 的仅限输出状态信息。此值应保存在客户端中，并与下一个 Assist RPC 一起在 DialogStateIn.conversation_state 字段中返回。（客户端无需解释或使用此值。）这些信息应该会在设备重新启动后自动保存。不过，在恢复出厂设置期间，此值应该会被清除（不保存在客户端中）。

microphone_mode

MicrophoneMode

仅限输出，用于指定处理此 Assist RPC 后麦克风的模式。

volume_percentage

int32

仅限输出：更新了音量。除非系统识别出语音指令（例如“调高音量”或“将音量设为 4”），否则该值将介于 1 到 100 之间（对应于 1% 到 100% 的新音量）。通常，客户端在播放 audio_out 数据时应使用此音量，并将此值保留为当前音量，并在下一个 AssistRequest 的 AudioOutConfig 中提供此值。（某些客户端可能还会实现其他方式来允许更改当前音量，例如提供用户可以旋转的旋钮。）

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 是一个标记值，表示未设置 stability。