构建项目

Actions Builder Actions SDK

Actions 项目会将您的所有 Action 打包到一个容器中。您需要将此项目发布到 Actions on Google，以便 Google 助理了解如何发现和调用您的对话体验。

您可以使用以下低级别组件构建 Actions 项目：

• 设置和资源用于定义项目元数据和资源（如项目图标）。Google 会使用这些信息将您的 Action 发布到 Google 助理目录，以便用户可以发现和调用它们。

• intent 表示要执行的任务，例如某些用户输入或需要处理的系统事件。最常用的 intent 类型是用户 intent。通过这些意图，您可以声明由 NLU（自然语言理解）引擎自然扩展的训练短语，以包含更多类似的短语。NLU 使用这些短语的聚合来训练 Google 助理用于匹配用户输入的语言模型。在对话期间，如果某些用户输入与该 intent 的语言模型匹配，Google 助理运行时会向您的 Action 发送该 intent，以便其处理该 intent 并响应用户。

• 类型可用于从用户输入中提取结构化数据。通过使用类型注释训练短语，NLU 可以为您提取相关的结构化数据，因此您不必解析开放式输入。

• 场景可处理 intent，是 Action 的主要逻辑执行程序。它们可以填充槽位、评估条件逻辑、向用户返回提示，甚至可以调用外部网络服务来执行业务逻辑。与 intent 结合使用时，您可以有效地检测特定的用户输入或系统事件并执行相应的逻辑。

• 提示定义了您用来回复用户的静态或动态响应。

• 网络钩子可让您将额外的工作委托给网络服务（执行方式），例如验证数据或生成提示。您的 Action 通过基于 JSON 的 webhook 协议与执行方式进行通信。

• Interactive Canvas：通过采用 HTML、CSS 和 JavaScript 的 Web 应用，打造丰富而沉浸式的体验。

创建项目

您必须先在 Actions 控制台中创建项目，然后才能针对 Google 助理开发应用。如需创建项目，请执行以下操作：

1. 转到 Actions 控制台。
2. 点击 New project。
3. 为你的项目输入名称，然后点击 Create Project。
4. 在 What kind of Action do you want to build? 屏幕中，选择最能代表您的项目的类别，然后点击 Next。
5. 在 How do you want to build it 屏幕中，选择一种构建方式，然后点击 Start building。例如，您可以从空项目或示例开始。

创建本地 Actions SDK 项目

在 Actions 控制台中创建 Actions 项目后，您就可以在本地开发环境中初始化该项目。

如需从现有 Actions 项目初始化 Actions SDK 项目，请按以下步骤操作：

1. 为本地文件系统上的 Actions 项目创建一个空目录。
2. 在这个空目录中，创建一个 sdk 目录。
3. 在终端中，将工作目录更改为 sdk 目录。

从空项目开始

如果要从您刚在控制台中创建的空项目开始，请运行 gactions pull --project-id <my-project-id>。

$ mkdir myAction
$ cd myAction
$ mkdir sdk
$ cd sdk
$ gactions pull --project-id my-project-id
Pulling your project files from Draft for a project id: "my-project-id"
✔ Done. You should see the files written in path/to/myAction/sdk

从示例项目入手

如果要从示例项目开始，请运行 gactions init <sample name>。

$ mkdir actions-test
$ cd actions-test
$ mkdir sdk
$ cd sdk
$ gactions init question
Writing sample files for question.
✔ Done. Please checkout the following documentation - https://developers.google.com/assistant/conversational/build on the next steps on how to get started.

定义项目信息

项目的设置和资源定义了有关项目的信息，例如功能和 surface 支持、支持的语言区域、显示名称、说明、徽标等。下表介绍了您提供的主要设置和资源。Actions on Google 会使用这些信息来部署您的项目并将其发布到 Google 助理目录。

名称	说明
目录信息	提供相关信息，以便 Actions on Google 可以将您的项目发布到 Google 助理目录。包括有关项目的元数据和摘要，以及徽标和横幅图片的图片资源。
地理位置定位	配置可使用您的 Action 的语言区域。
Surface 功能	配置可使用您的 Action 的 Surface。
公司详细信息	指定贵公司的联系信息。
品牌验证	关联您拥有的网站或 Android 应用可获得额外优势，例如在您的 Action 中预留调用名称和网站链接。
版本	为 Action 配置不同的测试版本和正式版，以用于测试和正式版。
Google 助理链接	允许用户从网站媒体资源调用您的 Action。

如需定义项目信息，请执行以下操作：

1. 在 sdk/settings/settings.yaml 中为您的 Actions 项目定义全局设置。如需了解支持的值，请参阅设置参考文档。

   以下代码段展示了一个示例 sdk/settings/settings.yaml 文件：

   accountLinking:
     enableAccountCreation: true
     linkingType: GOOGLE_SIGN_IN
   category: GAMES_AND_TRIVIA
   projectId: my-project-id
   ...
   

2. 在 sdk/settings/<locale>/settings.yaml 文件中定义可根据用户的语言区域而变化的设置（例如，不同语言的调用短语），并将“locale”替换为您的目标语言区域。

   如需了解支持的值，请参阅 LocalizedSettings 参考文档。

   以下代码段是在 sdk/settings/en/settings.yaml 文件中定义的英语设置的示例：

   localizedSettings:
     developerEmail: developer@developers.com
     developerName: Developer Name
     displayName: My Display Name
     fullDescription: full description of the action
     largeBannerImage: https://path/to/large/banner
     privacyPolicyUrl: http://path/to/privacy/policy
     sampleInvocations:
     - Talk to My Display Name
     shortDescription: short description of the action
     smallLogoImage: https://path/to/small/logo
     voice: female_1
   ...
   

添加资源

您可以在 Actions 项目中存储图片文件、音频文件和字符串等资源，并使用系统定义的 $resources 变量从配置文件（例如提示定义或条件）中引用这些资源。

项目资源存储在 resources/ 下，并为每种资源类型分配目录中的文件夹。

您可以通过在资源类型文件夹中创建特定于语言区域的文件夹对资源进行本地化，例如，您可以将西班牙语版本的字符串存储在 resources/strings/es/<filename>.yaml 中。

图像

图片文件存储在 resources/images/ 中，您可以使用 $resources.images.<name of the image file without file extension> 引用它们。允许的文件扩展名包括：

• gif
• png
• jpg
• jpeg

例如，如果小徽标的英文版本保存在 resources/images/en/square.png 中，英文版本的大横幅则分别保存在 resources/images/en/landscape.jpg 中，则上一个示例中的 sdk/settings/en/settings.yaml 将变为：

localizedSettings:
  developerEmail: developer@developers.com
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action

  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action

  smallLogoImage: $resources.images.square
  voice: female_1
...

音频文件

音频文件存储在 resources/audio/ 中，您可以使用 $resources.audio.<name of the audio file without file extension> 引用它们。

允许的文件扩展名包括：

• mp3
• mpeg

例如，您可以在问题中引用以下录音：

candidates:
  - first_simple:
      variants:
        - speech: your speech response
    content:
      media:
        mediaType: audio
        mediaObjects:
          - name: media name
            description: media description
            url: $resources.audio.intro

字符串

字符串作为 .yaml 文件存储在 resources/strings/ 中。每个文件均包含字符串键和关联值的映射，可以是单个字符串，也可以是字符串列表。对于单个字符串值（或从列表中获取随机值），您可以使用 $resources.strings.<name of the image file without file extension>.<key> 引用这些值，对列表中的特定字符串值使用 $resources.strings.<name of the image file without file extension>.<key>.<numerical index> 来引用这些值。

例如，使用资源字符串进行字符串本地化后，上一个示例中的 sdk/settings/en/settings.yaml 可能会变为：

localizedSettings:
  developerEmail: developer@developers.com
  developerName: $resources.strings.appinfo.developerName
  displayName: $resources.strings.appinfo.displayName
  fullDescription: $resources.strings.appinfo.fullDescription
  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: $resources.strings.appinfo.privacyPolicyUrl
  sampleInvocations:
  - $resources.strings.invocations.sample
  shortDescription: $resources.strings.appinfo.shortDescription
  smallLogoImage: $resources.images.square
  voice: female_1
...

在模拟器中测试项目

Actions 控制台提供了一个模拟器，供您预览 Action。借助该模拟器，您可以查看调试信息、设置设备功能、模拟语言区域等。

如需测试项目，请执行以下操作：

1. 运行 gactions deploy preview 以在模拟器中部署您的 Action，以便“预览”并启用测试。
2. 打开命令输出中的网址以访问模拟器。

$ gactions deploy preview
Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview