使用 Actions Builder 构建适用于 Google 助理的 Action（第 1 级）

Google 助理是一款虚拟智能个人助理，借助 Google 助理开发者平台，您可以打造软件，从而为超过 10 亿台设备（包括智能音箱、手机、汽车、电视、头戴式耳机等）扩展 Google 助理的功能。用户可通过对话与 Google 助理互动，以这种方式处理各种事务，例如购买日用品或约车。作为开发者，您可以使用 Google 助理开发者平台在用户和您自己的第三方履约服务之间轻松打造并管理愉悦、高效的对话体验。

本 Codelab 介绍了 Google 助理相关开发的初级概念；您无需事先熟悉相关平台也可完成学习。在本 Codelab 中，您将构建一个适用于 Google 助理的简单 Action；当用户开始探索神秘大陆 Gryffinberg 后，该 Action 可以告知用户其运势信息。在 Actions Builder 第 2 级 Codelab 中，您可以进一步构建该 Action，根据用户输入自定义用户的运势信息。

构建内容

在本 Codelab 中，您将构建具有以下功能的简单 Action：

• 使用问候消息回应用户
• 向用户提问。在用户回答问题后，您的 Action 会对用户的选择做出适当的响应
• 提供建议内容信息卡，用户点击该信息卡即可输入相应内容
• 根据用户是否为回访用户修改问候消息

完成本 Codelab 的学习后，您构建的 Action 将具有以下对话流：

学习内容

• 如何在 Actions 控制台中创建项目
• 如何在用户调用您的 Action 后向其发送提示
• 如何处理用户输入并返回响应
• 如何在 Actions 模拟器中测试您的 Action
• 如何使用 Cloud Functions 编辑器实现执行方式

所需条件

您的环境中必须安装以下工具：

• 网络浏览器，例如 Google Chrome

以下部分介绍了如何设置开发环境，以及如何创建 Actions 项目。

检查您的 Google 权限设置

如需测试您在本 Codelab 中构建的 Action，您需要启用必要的权限，以便模拟器能够访问您的 Action。如需启用权限，请按以下步骤操作：

1. 转到活动控件页面。
2. 使用您的 Google 帐号登录（如果您尚未登录的话）。
3. 启用以下权限：

• 网络与应用活动记录
• 在网络与应用活动记录下，选中包括 Chrome 历史记录和使用 Google 服务的网站、应用和设备上的活动记录旁边的复选框。

创建 Actions 项目

Actions 项目是 Action 的容器。如需为本 Codelab 创建 Actions 项目，请按以下步骤操作：

1. 打开 Actions 控制台。
2. 点击 New project。
3. 输入 Project name，例如 actions-codelab。（该名称供内部参考。之后您还可以为项目设置外部名称。）

4. 点击 Create project。
5. 在 What kind of Action do you want to build? 屏幕中，选择 Custom 卡片。
6. 点击 Next。
7. 选择 Blank project 卡片。
8. 点击 Start building。

关联结算帐号

如果您需要以后使用 Cloud Functions 在本 Codelab 中部署执行方式，则必须为 Google Cloud 中的项目关联结算帐号。如果您已有结算帐号，可以忽略以下步骤。

如需为您的项目关联结算帐号，请按以下步骤操作：

1. 转到 Google Cloud Platform 结算页面。
2. 点击添加结算帐号。
3. 填写付款信息，然后点击开始免费试用或提交并启用结算功能。
4. 点击页面顶部的我的项目标签页。
5. 在 Actions 下，点击本 Codelab 的 Actions 项目旁边的三点状图标。
6. 点击更改结算信息。
7. 在下拉菜单中，选择您配置的结算帐号。点击设置帐号。

为避免产生费用，请按照本 Codelab 末尾的“后续步骤”页面中“清理项目”部分所述的步骤操作。

用户通过“调用”与您的 Action 开始对话。例如，如果您的 Action 名为“MovieTime”，用户可以使用如下指令调用您的 Action：“Hey Google, talk to MovieTime”，其中 MovieTime 为显示名。如果您要将 Action 部署到生产环境，则该 Action 必须具有显示名；不过，您无需定义显示名即可测试 Action。相反，您可以在模拟器中使用指令“Talk to my test app”调用 Action。

您必须修改主调用，定义在用户调用您的 Action 后会发生什么。

关键术语：

• 主调用：可让用户开始与 Action 对话的入口点。在用户说出类似于“Hey Google, talk to <display name>”的指令后，主调用会触发并对用户做出响应。

默认情况下，Actions Builder 会在您的调用触发后提供通用提示（“Start building your Action by defining main invocation.”）。

关键术语：

• 提示：定义您的 Action 发送给用户的响应内容。提示可以是简单的文本和语音响应，也可以是丰富的消息，例如卡片和图片。

您可以使用特殊提示 Canvas 向用户返回全屏视觉元素。如需详细了解 Canvas，请参阅 Interactive Canvas 文档。

在下一部分中，您将在 Actions 控制台中为主调用自定义提示。

设置主调用

如需修改 Action 在被用户调用后向用户发回的提示，请按以下步骤操作：

1. 点击导航栏中的 Main invocation。

2. 在代码编辑器中，将 speech 字段 (Start building your action...) 中的文本替换为以下欢迎消息：A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.

注意：您可以使用 YAML 或 JSON 格式修改提示。

3. 点击 Save。

在模拟器中测试主调用

Actions 控制台提供了用于测试 Action 的网络工具，称为模拟器。界面会模拟硬件设备及其设置，让您可以与 Action 进行对话，就像该 Action 在智能显示屏、手机、音箱或 KaiOS 上运行时一样。

注意：您可以在 Actions 模拟器指南中了解有关如何使用 Actions 控制台模拟器的最新信息。如果您在后续步骤中遇到任何问题，请参阅该指南。

现在，当您调用相应的 Action 时，该 Action 应该会以您添加的自定义提示作为响应（“A wondrous greeting, adventurer!...”）

若要在模拟器中测试 Action 的主调用，请按以下步骤操作：

1. 在顶部导航栏中，点击 Test 以转到模拟器。
2. 如需在模拟器中调用您的 Action，请在左上角的 Input 字段中输入 Talk to my test app，然后按 Enter 键。

提示：您也可以点击建议贴块 Talk to my test app，或者点击麦克风图标，然后说出“Talk to my test app”，以调用您的 Action。

在您触发 Action 的主调用后，Google 助理会使用您的自定义欢迎消息进行响应。此时，对话在 Google 助理使用问候语进行响应后便会结束。在下一部分中，您将修改 Action，让对话能够继续。

查看事件日志

进入 Test 标签页后，右侧面板会显示事件日志，此类日志会以事件日志形式显示对话记录。每个事件日志都会显示在其对应的那轮对话期间发生的事件。

您的 Action 目前有一个事件日志，它显示了用户的输入（“Talk to my test app”）和 Action 的响应。下方的屏幕截图显示了该 Action 的事件日志：

如果您点击事件日志中的向下箭头，就可以看到其对应的那轮对话期间发生的事件（按时间顺序排列）：

• userInput：与用户的输入（“Talk to my test app”）对应。
• interactionMatch：与由用户输入触发的 Action 主调用响应对应。如果您点击相应箭头来展开该行，便可以看到您为主调用添加的提示 (A wondrous greeting, adventurer!...)
• endConversation：与在 Main invocation intent 中选择的过渡（目前会结束对话）对应。（您将在本 Codelab 的下一部分中详细了解过渡。）

您可以通过事件日志了解 Action 的运作情况，并且在您遇到任何问题时，也可以将其作为调试 Action 的实用工具。如需查看某个事件的详细信息，请点击对应的事件名称旁边的箭头，具体如以下屏幕截图所示：

现在，您已经定义了在用户调用您的 Action 后会发生什么，接下来，您可以构建 Action 对话的其余内容了。在继续学习本 Codelab 之前，请先熟悉以下术语以了解 Action 对话的工作原理：

关键术语：

• 场景：Action 的构建块，用于处理用户输入，通常还用于生成对用户的响应。用户 intent 通常可以激活其他场景，不过场景也可通过其他方式激活。
• 用户 intent：定义 Action 可以理解的用户输入。您可以为这类 intent 定义训练指令短语。当用户说出与训练指令短语匹配或类似的内容后，系统便会匹配对应的 intent。
• 训练指令短语：针对用户可能会说的与 intent 匹配的话语给出的示例。Google 助理自然语言理解 (NLU) 引擎会自然地拓展这类训练指令短语，以包含其他类似短语。
• 过渡：定义在满足条件后要过渡到哪个场景。

Action 可以有一个或多个场景，您必须先激活各个场景，Action 才能运行。（您在本 Codelab 中构建的 Action 只有一个标题为“Start”的场景。）激活场景的最常用方法是配置 Action，使得在用户说出的话语与场景中的用户 intent 匹配时，相应 intent 会触发向另一个场景的过渡并激活该场景。

例如，假设有一个 Action 可以为用户提供动物知识。当用户调用该 Action 后，系统会匹配到 Main invocation intent，这个 intent 会触发向名为“Facts.”的场景的过渡。该过渡会激活 Facts 场景，继而向用户发送以下提示：Would you like to hear a fact about cats or dogs?。Facts 场景中包含名为 Cat 的用户 intent，其中包含用户在想了解与猫相关的知识时可能会说出的训练指令短语，例如“I want to hear a cat fact”或“cat”。在用户要求听取与猫相关的知识后，系统会匹配到 Cat intent，这个 intent 会触发向名为“Cat fact.”的场景的过渡。Cat fact 场景会激活包含猫相关知识的提示并将其发送给用户。

图 1. 使用 Actions Builder 构建的 Action 中的一轮典型对话的流程。

场景、intent 和过渡共同构成对话的逻辑，并且定义了用户在您的 Action 对话中可能选择的各种路径。在下一部分中，您将创建一个场景，并定义在用户调用您的 Action 后如何激活该场景。

从主调用过渡到场景

在本部分中，您将创建一个名为“Start”的新场景，它会向用户发送提示，以询问用户是否要了解自己的运势。此外，您还要添加从主调用到新的 Start 场景的过渡。

如需创建该场景并添加到该场景的过渡，请按以下步骤操作：

1. 点击顶部导航栏中的 Develop。然后，点击左侧导航栏中的 Main invocation。
2. 在右侧的 Transition 部分中，点击下拉菜单，然后在文本字段中输入 Start。

3. 点击 Add。这样即可创建一个名为“Start”的场景，并告知 Action 在向用户发送欢迎提示后过渡到 Start 场景。
4. 点击左侧导航栏中的 Scenes 以显示场景列表。
5. 在 Scenes 下，点击 Start 以查看 Start 场景。
6. 点击 Start 场景的 On enter 部分中的 +。
7. 选择 Send prompts。
8. 将 speech 字段中的句子 (Enter the response that users will see or hear...) 替换为向用户询问的问题：Before you continue on your quest, would you like your fortune told?

9. 点击 Save。

当用户进入 Start 场景后，Google 助理会向用户提供该提示 (Before you continue on your quest...)。

添加建议内容信息卡

建议内容信息卡可以为用户提供可点击的建议内容，而您的 Action 可以将此类内容作为用户输入进行处理。在本部分中，您将添加在刚才配置的提示 (Before you continue on your quest, would you like your fortune told?) 下方显示的建议内容信息卡，以便为使用带屏幕设备的用户提供支持。

如需在 Start 场景的提示中添加建议内容信息卡，请按以下步骤操作：

1. 在 Start 场景中，点击代码编辑器下方的建议。该操作可以添加一个建议内容信息卡。
2. 在 title 字段中，将 Suggested Response 替换为 'Yes'。
3. 按相同的格式手动添加标题为“'No'”的建议内容信息卡。您的代码应类似于以下代码段：

    suggestions:
      - title: 'Yes'
      - title: 'No'

4. 点击 Save。

在模拟器中测试 Action

此时，您的 Action 应该会从主调用过渡到 Start 场景，并询问用户是否要了解自己的运势。模拟显示屏中还应显示建议内容信息卡。

如需在模拟器中测试您的 Action，请按以下步骤操作：

1. 在导航栏中，点击 Test 以转到模拟器。
2. 为了在模拟器中测试 Action，请在 Input 字段中输入 Talk to my test app。
3. 按 Enter 键。您的 Action 应该以 Main invocation 提示和添加的 Start 场景提示（“Before you continue on your quest, would you like your fortune told?”）作为响应。

以下屏幕截图显示了该互动情况：

注意：事件日志会记录当前会话中与模拟器进行的每次互动，因此您之前在本 Codelab 中进行的测试所生成的日志记录会显示为第一个事件日志。如需清除事件日志，请点击 Reset Test。

4. 点击 Yes 或 No 建议内容信息卡以响应提示。（您也可以说“Yes”或“No”，或在 Input 字段中输入 Yes 或 No。）

在您响应提示后，您的 Action 会以一条消息作为响应，指出其无法理解您的输入：“Sorry, I didn't catch that. Can you try again?”由于您尚未配置 Action 来使其理解和响应“Yes”或“No”输入，因此该 Action 会将您的输入匹配到 NO_MATCH intent。

关键术语：

• NO_MATCH：当用户说出无法与 Action 中的其他 intent 匹配的内容时系统会匹配的通用 intent。
• 系统 intent：默认配置的 intent，用于处理常见的系统事件，例如用户未提供输入的事件。NO_MATCH 和与主调用关联的 intent 都是系统 intent 的示例。

默认情况下，NO_MATCH 系统 intent 会提供通用响应，但您可以自定义此类响应，以向用户表明您无法理解其输入。如果无法匹配用户输入的次数达到 3 次，Google 助理就会结束用户与 Action 之间的对话。

添加 yes intent 和 no intent

现在，用户可以响应您的 Action 提出的问题了，接下来您可以配置该 Action，使其能够理解用户的响应（“Yes”或“No”）。在后面的部分中，您将创建在用户说出“Yes”或“No”后系统所匹配的用户 intent，然后向 Start 场景添加相应 intent。

创建 yes intent

如需创建 yes intent，请按以下步骤操作：

1. 点击导航栏中的 Develop 按钮。
2. 点击导航栏中的 Intents 以打开 intent 列表。
3. 点击 intent 列表底部的 +（加号）。将新 intent 命名为 yes，然后按 Enter。
4. 点击 yes intent 以打开 yes intent 页面。
5. 在 Add training phrases 部分中，点击 Enter Phrase 文本框，然后输入以下短语：

• Yes
• Y
• I would
• Tell me

6. 点击 Save。

向 Start 场景添加 yes intent

现在，如果用户表达“yes”intent，该 Action 便可以正确理解了。您可以向 Start 场景添加 yes 用户 intent，因为用户响应的是 Start 提示（“Before you continue on your quest, would you like your fortune told?”）。

如需向 Start 场景添加该用户 intent，请按以下步骤操作：

1. 点击导航栏中的 Start 场景。
2. 点击 Start 场景中的 User intent handling 旁边的 +（加号）。
3. 在 intent 下拉菜单中选择 yes。

4. 点击 Send prompts，然后将 speech 字段更新为以下文本：Your future depends on the aid you choose to use for your quest. Choose wisely! Farewell, stranger.

编辑器中的代码应类似于以下代码段：

 candidates:
  - first_simple:
      variants:
        - speech: >-
            Your future depends on the aid you choose to use for your quest. Choose
            wisely! Farewell, stranger.

5. 在 Transition 部分中，点击下拉菜单，然后选择 End conversation。
6. 点击 Save。

在模拟器中测试 yes intent

此时，如果用户要听取自己的运势，您的 Action 便可以正确理解并返回适当响应了。

如需在模拟器中测试该 intent，请按以下步骤操作：

1. 在导航栏中，点击 Test。
2. 为了在模拟器中测试您的 Action，请在 Input 字段中输入 Talk to my test app，然后按 Enter 键。
3. 在 Input 字段中输入 Yes，然后按 Enter 键。或者，点击 Yes 建议内容信息卡。

您的 Action 会响应用户，并根据用户选择的辅助物告知其对应的运势。然后，Action 会终止对话，因为您为 yes intent 选择了 End conversation 过渡。

创建 no intent

现在，您需要创建 no intent，以使 Action 在用户不想听取运势时正确理解并做出响应。如需创建该 intent，请按以下步骤操作：

1. 点击导航栏中的 Develop 按钮。
2. 点击导航栏中的 Intents 以打开 intent 列表。
3. 点击 intent 列表底部的 +（加号）。将新 intent 命名为 no，然后按 Enter 键。
4. 点击 no 以打开 no intent 页面。
5. 在 Add training phrases 部分中，点击 Enter Phrase 文本框，然后输入以下短语：

• No
• N
• I don't want
• nope

6. 点击 Save。

向 Start 场景添加 no intent

现在，如果用户表达“no”或类似于“no”的内容（例如“nope”），该 Action 便可以正确理解了。您需要向 Start 场景添加 no 用户 intent，因为用户响应的是 Start 提示（“Before you continue on your quest, would you like your fortune told?”）。

如需为 Start 场景添加该 intent，请按以下步骤操作：

1. 点击导航栏中的 Start 场景。
2. 点击 Start 场景中的 User intent handling 旁边的 +（加号）。
3. 在 Intent 部分中，从下拉菜单中选择 no。

4. 点击 Send prompts，然后将 speech 字段更新为以下文本：I understand, stranger. Best of luck on your quest! Farewell。

编辑器中的代码应类似于以下代码段：

 candidates:
  - first_simple:
      variants:
        - speech: >-
             I understand, stranger. Best of luck on your quest! Farewell.

5. 在 Transition 部分中，从下拉菜单中选择 End conversation。
6. 点击 Save。

在模拟器中测试 no intent

此时，如果用户不想听取自己的运势，您的 Action 便可以正确理解并返回适当响应了。

如需在模拟器中测试该 intent，请按以下步骤操作：

1. 在导航栏中，点击 Test。
2. 在 Input 字段中输入 Talk to my test app，然后按 Enter。
3. 在 Input 字段中输入 No，然后按 Enter。或者，点击 No 建议内容信息卡。

Action 会祝用户在旅途中一帆风顺，而不会提供其运势。然后，Action 会终止对话，因为您为 no intent 选择了 End conversation 过渡。

目前，您的 Action 响应是静态的；激活包含提示的场景后，您的 Action 每次都会发送相同的提示。在本部分中，您将实现包含用于构建动态对话响应的逻辑的执行方式。

关键术语：

• 执行方式：包含 Action 逻辑的代码。网络钩子会根据 Action 中发生的事件来触发对该执行方式的调用。

您的执行方式会识别用户是回访用户还是新用户，并针对回访用户修改 Action 的问候消息。针对回访用户的问候消息会简短一些，并会对用户的回访做出肯定回应：“A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!”

对于本 Codelab，请使用 Actions 控制台中的 Cloud Functions 编辑器修改和部署执行方式代码：

关键术语：

• Cloud Functions 编辑器：Actions 控制台的内置编辑器，借助于该编辑器，您可以使用 Cloud Functions for Firebase 修改和部署执行方式代码。

您的 Action 可以触发网络钩子，以将在调用期间或场景执行的特定部分中发生的事件通知您的执行方式。系统触发网络钩子后，您的 Action 会向执行方式发送一个包含 JSON 负载的请求以及事件处理脚本的名称。该处理脚本会执行一些逻辑并返回对应的 JSON 响应。

构建执行方式

现在，您可以在内嵌编辑器中修改执行方式，以便在回访用户和新用户调用您的 Action 后，针对这两种用户生成不同的提示。

如需向执行方式添加该逻辑，请按以下步骤操作：

1. 点击导航栏中的 Develop 按钮。
2. 点击导航栏中的 Webhook 标签页。
3. 选择 Inline Cloud Functions，然后点击 Confirm。系统会自动为 index.js 和 package.json 文件添加样板代码。

4. 将 index.js 的内容替换为以下代码：

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

5. 点击 Save Fulfillment。
6. 点击 Deploy Fulfillment。

等待几分钟，让 Cloud Functions 预配并部署您的执行方式。您应该会在代码编辑器上方看到 Cloud Function deployment in progress... 消息。代码部署成功后，该消息会更新为 Your Cloud Function deployment is up to date。

了解代码

您的执行方式（使用适用于 Node.js 的 Actions on Google 执行方式库）可以响应来自 Google 助理的 HTTP 请求。

在前面的代码段中，您定义了 greeting 处理脚本，它会通过检查 lastSeenTime 属性来检查用户之前是否访问过相应 Action。如果未定义 lastSeenTime，则表示用户为新用户，greeting 处理脚本会提供针对新用户的问候语。

更新主调用以触发网络钩子

现在，您已经定义了 greeting 函数，接下来您可以在主调用 intent 中配置 greeting 事件处理脚本，以让您的 Action 知道在被用户调用后应该调用该函数。

如需配置您的 Action，使其能调用新的 greeting 处理脚本，请按以下步骤操作：

1. 点击导航栏中的 Main invocation。
2. 取消选择 Send prompt，然后选择 Call your webhook。
3. 在文本框中添加 greeting。

4. 点击 Save。

在模拟器中测试更新后的主调用

如需在模拟器中测试您的 Action，请按以下步骤操作：

1. 在导航栏中，点击 Test 以转到模拟器。
2. 为了在模拟器中测试您的 Action，请在 Input 字段中输入 Talk to my test app，然后按 Enter。

由于您之前在本 Codelab 中测试过 Action，已不属于新用户，因此您会收到以下简短版的问候语：“A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!...”

恭喜您！

您已经掌握了构建适用于 Google 助理的 Action 所需的基础技能。

所学内容

• 如何使用 Actions 控制台设置 Actions 项目
• 如何向主调用添加提示，以便用户与您的 Action 开始会话
• 如何使用场景、intent、过渡、建议内容信息卡和执行方式创建对话界面
• 如何使用 Actions 模拟器测试 Action

其他学习资源

探索以下资源，详细了解如何构建适用于 Google 助理的 Action：

• 学习使用 Actions Builder 构建适用于 Google 助理的 Action（第 2 级）Codelab，继续构建本 Codelab 中的对话 Action
• 访问官方文档网站，了解如何开发适用于 Google 助理的 Action
• 访问 Actions on Google GitHub 页面，查看示例代码和库
• 访问官方 Reddit 社区，与从事 Google 助理相关工作的开发者互动

欢迎关注我们的 Twitter 帐号 @ActionsOnGoogle，及时了解我们的最新公告，还可以使用标签 #AoGDevs 发布 Twitter 微博，分享您构建的成果！

清理项目 [推荐]

注意：在第 2 级 Codelab 使用 Actions Builder 构建适用于 Google 助理的 Action（第 2 级）中，您将以在本 Codelab 中创建的项目为基础进行构建。如果您计划学习第 2 级 Codelab，请勿删除项目；不过，您可以在第 2 级 Codelab 末尾的“清理项目”部分将其删除。

为避免可能产生的费用，建议您移除不想使用的项目。如需删除您在本 Codelab 中创建的项目，请按以下步骤操作：

1. 如需删除 Cloud 项目和资源，请完成关停（删除）项目部分中所列的步骤。

注意：请确保在 Google Cloud Platform 设置页面中正确选择要删除的项目。

2. 可选：如需立即从 Actions 控制台移除您的项目，请完成删除项目部分中所列的步骤。如果您未完成该步骤，系统会在大约 30 天后自动移除您的项目。

反馈意见调查

在您离开本页面前，请填写简短的调查问卷，与我们分享您的体验。