对话型 Action 已于 2023 年 6 月 13 日弃用。如需了解详情，请参阅对话型 Action 停用。

此页面由 Cloud Translation API 翻译。

Package google.assistant.embedded.v1alpha2

索引

EmbeddedAssistant（接口）
AssistConfig（消息）
AssistRequest（消息）
AssistResponse（消息）
AssistResponse.EventType（枚举）
AudioInConfig（消息）
AudioInConfig.Encoding（枚举）
AudioOut（消息）
AudioOutConfig（消息）
AudioOutConfig.Encoding（枚举）
DebugConfig（消息）
DebugInfo（消息）
DeviceAction（消息）
DeviceConfig（消息）
DeviceLocation（消息）
DialogStateIn（消息）
DialogStateOut（消息）
DialogStateOut.MicrophoneMode（枚举）
ScreenOut（消息）
ScreenOut.Format（枚举）
ScreenOutConfig（消息）
ScreenOutConfig.ScreenMode（枚举）
SpeechRecognitionResult（消息）

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` 如需了解详情，请参阅身份验证指南。

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 个样本）。如果音频发送速度明显变快或变慢，系统将会返回错误。

联合字段 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

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` 消息中接收。

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

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` 字段。但是，这会显著增加响应延迟时间。

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 项目处于预览模式时，系统才会填充此字段。

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 针对给定的特征指定。

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 的组合之前必须已通过设备注册关联。

device_id

string

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

device_model_id

string

必需：设备型号的唯一标识符。device_model_id 和 device_id 的组合之前必须已通过设备注册关联。

DeviceLocation

位置有三种来源。它们的使用方式如下：

此 DeviceLocation，主要用于带有 GPS 的移动设备。
用户在设备设置期间指定的位置；此位置针对每个用户、每个设备。如果未指定 DeviceLocation，则使用此位置。
根据 IP 地址推断位置。仅当您未指定上述任何一项时，才使用此参数。

字段

字段
`coordinates`	`LatLng` 设备的纬度和经度。

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

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` 发出查询时设备当前的可视化屏幕模式。

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`。

transcript

string

仅限输出：表示用户所说字词的转录文本。

stability

float

仅限输出：对 Google 助理不会改变其对此结果的猜测的可能性的估计。值的范围为 0.0（完全不稳定）至 1.0（完全稳定且最终版本）。默认值 0.0 是一个标记值，表示未设置 stability。