您的设备可能具有当前这组特征 未涵盖的特殊能力,例如“闪烁我的灯光”特征是指可以让指示灯闪烁的设备。您可以为设备定义自定义操作,指定发送到设备的命令以触发特殊功能。
如需定义自定义设备操作,您需要以下内容:
- 与用户查询匹配的模式
- 与匹配查询相关联的自定义设备操作
- 向用户朗读的文本(如果设备支持此操作)
- 发送回设备的命令名称,以及所有参数
您可以通过将这些信息放入操作包来创建自定义设备操作。操作包定义了 Google 助理响应的格式。与 Actions SDK 不同,自定义设备操作在本地执行;您无需指定端点来处理请求和提供响应。自定义设备操作本质上不是对话式的。
创建 Action 包
以以下示例为例,创建一个定义测试命令的文件(如 actions.json
):闪烁 LED。 从您在上一步中下载的示例代码复制该文件:
cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/library/
cp ~/assistant-sdk-python/google-assistant-sdk/actions.json .
{
"manifest": {
"displayName": "Blinky light",
"invocationName": "Blinky light",
"category": "PRODUCTIVITY"
},
"actions": [
{
"name": "com.example.actions.BlinkLight",
"availability": {
"deviceClasses": [
{
"assistantSdkDevice": {}
}
]
},
"intent": {
"name": "com.example.intents.BlinkLight",
"parameters": [
{
"name": "number",
"type": "SchemaOrg_Number"
},
{
"name": "speed",
"type": "Speed"
}
],
"trigger": {
"queryPatterns": [
"blink ($Speed:speed)? $SchemaOrg_Number:number times",
"blink $SchemaOrg_Number:number times ($Speed:speed)?"
]
}
},
"fulfillment": {
"staticFulfillment": {
"templatedResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Blinking $number times"
}
},
{
"deviceExecution": {
"command": "com.example.commands.BlinkLight",
"params": {
"speed": "$speed",
"number": "$number"
}
}
}
]
}
}
}
}
],
"types": [
{
"name": "$Speed",
"entities": [
{
"key": "SLOWLY",
"synonyms": [
"slowly",
"slow"
]
},
{
"key": "NORMALLY",
"synonyms": [
"normally",
"regular"
]
},
{
"key": "QUICKLY",
"synonyms": [
"quickly",
"fast",
"quick"
]
}
]
}
]
}
前面的示例使用以下信息来定义自定义设备操作:
- 与用户查询匹配的模式(闪烁 N 次)
- 出于组织目的与匹配查询 (
com.example.actions.BlinkLight
) 关联的自定义设备操作 - 如果设备支持该操作,向用户朗读的文本(闪烁 N 次)
- 发送回设备的命令名称 (
com.example.commands.BlinkLight
),以及所有参数(数字,可能还有速度说明)
如需定义查询格式,请注意以下事项:
- 您可以在查询格式中使用 schema.org 定义的类型。
types [...]
数组用于定义自定义类型(例如$Speed
)的列表。- 您可以在查询句式中使用自定义类型。用户可以说出自定义类型中的任何同义词,以便与查询句式相匹配。
- 当同义词匹配时,类型实例 (
speed
) 将返回标准化键 (SLOWLY
)。可能有多个实体,例如,不同的灯支持不同的闪烁速度。 - 请求 TTS 模式的部分内容是可选的。例如,在查询句式中使用
($Speed:speed)?
可使此部分成为可选部分。 - 响应 TTS 中的
$type.raw
(例如$speed.raw
)会替换为用户实际说出的字词。
如需查看其中许多字段的说明,请参阅 ActionPackage 文档。
部署操作包
在 Action 软件包中构建自定义设备操作后,您可以让 Google 助理访问该 Action 软件包。
虽然您可以在设备上执行本部分中的步骤,但在开发系统上执行这些步骤可能会更容易。以下命令不需要虚拟环境即可运行。
下载
gactions
命令行工具。从
gactions
工具所在的目录中移除所有现有凭据。rm creds.data
使用
gactions
CLI 将 Action 包保存到 Google。将project_id
替换为您的 Actions 控制台项目 ID。./gactions update --action_package actions.json --project project_id
首次运行此命令时,系统会提供一个网址并要求您登录。复制网址并将其粘贴到浏览器中(可在任何系统上完成)。 该页面会要求您登录自己的 Google 账号。登录在先前 步骤中创建项目的 Google 帐号。
从 API 批准权限请求后,您的浏览器会显示代码,例如“4/XXXX”。复制此代码并将其粘贴到终端中:
Enter the authorization code:
如果授权成功,您将看到类似于以下内容的响应:
Your app for the Assistant for project my-devices-project was successfully updated with your actions.
使用
gactions
CLI 将 Action 软件包部署到测试模式。在运行此命令之前,您必须向 Google 至少保存一次 Action 包。在测试模式下,系统只会在您的用户帐号中启用 Action 包。./gactions test --action_package actions.json --project project_id
目前,您无法使用 Actions 模拟器测试项目。
如需更新 Action 软件包,请使用
gactions update
命令。(可选)您可以创建本地化的 Action 软件包,以便在单个项目中同时支持许多不同的语言和语言区域。
修改示例
在设备上执行本部分中的步骤。
nano hotword.py
为您的自定义操作添加处理程序。如果您想使用上面的示例 Action 包,可以使用下面的处理程序。
import time # Add this to the imports near the top of the file ... if event.type == EventType.ON_DEVICE_ACTION: for command, params in event.actions: print('Do command', command, 'with params', str(params)) # Add the following lines after the existing line above: if command == "com.example.commands.BlinkLight": number = int( params['number'] ) for i in range(int(number)): print('Device is blinking.') # GPIO.output(25, 1) time.sleep(1) # GPIO.output(25, 0) time.sleep(1)
运行示例
运行修改后的源代码。
python hotword.py --device-model-id my-model
请尝试查询。对于上面的示例,请尝试以下操作:
Ok Google,眨眼 5 次。
请注意,查询需要与 Action 包中的查询格式匹配。