语音助手集成（可选）

[English Version]

请确保您已将 RainMaker 部署至 AWS 账户。 在开始以下配置前，请首先在 RainMaker 手机应用（或您自定义的应用）中创建新用户，并将某一节点关联到此用户。

语音助手集成

  • 借助 Smart Home Skill，通过 Alexa 控制 RainMaker 节点。
  • 借助 Smart Home Actions，通过谷歌语音助手 (Google Voice Assistant, GVA) 控制 RainMaker 节点。

创建 Skill 或 Action

创建 Alexa Smart Home Skill

Alexa Developer Create Account

Alexa Developer Console

  • 创建 Skill，如下图所示。在这一步中，选择 Smart Home 选项。

Create Smart Home Skill

  • 记下您的 Skill ID，这一 ID 将用于为 Alexa Skill Lambda 创建智能家居触发器。

Skill ID

  • 点击左侧导航栏中的 ACCOUNT LINKING 并记下底部 Alexa Redirect URLs 字段的内容，这些内容将被用于组成 Alexa 的回调 URL。

Account Linking

创建谷歌 Smart Home Actions

GVA First Action Creation

  • 如果您已经创建过 Google Actions 项目，您将看到以下界面：

GVA Creation

  • 选择 Smart Home 选项卡并点击 Start Building。

GVA Smart Home Action Creation

  • 打开 Project Settings，记下您的 Project ID。

GVA Project Settings

  • 您的 Google Actions 项目的回调 URL 将为 https://oauth-redirect.googleusercontent.com/r/<project-id>。

GVA Callback URLs

为 Alexa 和谷歌语音助手创建 AWS Cognito 应用客户端

部署 SAR 应用的前提条件

  1. 参照 配置自定义域名 中的步骤创建 Cognito 域。

RainMaker Dashboard Domain Name

  1. 记下身份提供商的名称。
  • 要获取 RainMaker 部署中配置的身份提供商列表，请进入 RainMaker 管理面板，点击左侧导航栏中的 Deployment Settings。
  • 点击 Identity Providers。
  • 记下 Identity Provider 一栏中的身份提供商名称。
  • 如果您配置的身份提供商包括谷歌、GitHub 和苹果，那么在部署 ESP-RainMaker-3p-CognitoClients SAR 应用时，SkillIdentityProviders 的值将包括 Google、GitHub、SignInWithApple 和 COGNITO。

注意： 若未配置身份提供商，那么 SkillIdentityProviders 的默认值将为 COGNITO。

RainMaker Dashboard IDP List

  1. 参考创建 Alexa Smart Home Skill 小节中的步骤，记下 AlexaCognitoCallbackURL 和 SkillId。

  2. 参考创建谷歌 Smart Home Actions 小节中的步骤，记下 GVACallbackURLs。

部署 ESP-RainMaker-3p-Cognito 客户端 SAR 应用

  • 前往 AWS 控制台，搜索 "Serverless Application Repository" 或 "SAR"。
  • 打开 Private applications 并勾选复选框 Show apps that create custom IAM roles or resource policies。

SAR Private Application

  • 搜索并点击打开 ESP-RainMaker-3p-CognitoClients。

ESP-RainMaker-3p-CognitoClients SAR Application

  • 在以下字段中输入相应值，完成后点击 Deploy。
  1. AlexaCognitoCallBackUrls - 具体参数值请参阅 创建 Alexa Smart Home Skill 小节。
  2. GVACognitoCallBackUrls - 具体参数值请参阅 创建谷歌 Smart Home Actions 小节。
  3. SkillIdentityProvidersNewUserPool - 输入您准备配置的身份提供商，具体名称可参阅 为 Alexa 和谷歌语音助手创建 AWS Cognito 应用客户端 小节。
  4. SkillIdentityProviders - 保持默认值即可。

ESP-RainMaker-3p-CognitoClients deployment

其他参数值可保持不变，然后点击 Deploy。

  • 部署成功后，您将看到如下页面：

ESP-RainMaker-3p-CognitoClients deployment success

  • 部署完成后，系统将为 Alexa Skill 和 Google Actions 创建 AWS Cognito 应用客户端。

配置语音助手集成的前提条件

获取 RainMaker API 终端节点 URL

  • Alexa 谷歌语音助手处理程序将调用 RainMaker API 终端节点 URL 以获取设备信息，因此，RainMaker API URL 需作为一个给定值输入至 ESP-RainMaker-3P-Integrations 应用中。

  • 进入 AWS 控制台，搜索并点击打开 CloudFormation。请确保所选区域为 RainMaker 部署区域。

Search Cloudformation

  • 启用 View nested 选项。

View Nested Cloudformation

  • 搜索 "ESP-RainMaker-Base-API"，在 Outputs 窗格中找到 RainmakerAPIUrl。

Search ESP-RainMaker-Base-API

  • RainMaker 后端 API 终端节点 URL 为 <RainmakerAPIUrl>/v1/。 请记下该值，后续填写 APIEndPointURL 字段时将会用到。

启用谷歌异步消息传输并获取谷歌消息传输客户端的详细信息

谷歌语音助手处理程序将主动向谷歌云的 Home Graph 服务报告设备状态，因此您需要创建一个谷歌服务账号 (Google Service Account) 并将该账号添加至处理程序中。

如果您需要部署 Google Actions，请参考以下步骤以获取账号凭证：

  1. 在您的账户中启用 Home Graph API。以下为详细步骤：
  • 前往 谷歌 Home Graph 主页。
  • 在顶部的下拉菜单中，选择您在前面步骤中创建的智能家居项目。
  • 点击 Enable。
  1. 创建一个服务账号密钥文件。
  • 前往 谷歌服务账号主页。
  • 选择您在上一步中创建的智能家居项目。
  • 点击 Create Service Account 选项。
  • 在 Service Account Name 字段下，输入合适名称。
  • 在 Description 中，输入 "Service Account for report state token creation"。
  • 点击 Create and Continue。
  • 在下一步中，选择角色类型 (role type) 为 Service Accounts，并选择角色 (role) 为 Service Account token creator。
  • 点击 Continue，然后点击 Done。
  • 服务账号已经创建，现在需要添加使用服务账号的密钥。
  • 点击已创建的服务账号电子邮件。
  • 打开 Keys 选项，点击 Add Key。
  • 选择 Create Key 选项。
  • 选择密钥类型为 JSON。
  • 系统将为您下载服务账号文件，其中包含所需的账号凭证信息。
  • 打开下载的服务账号文件。
  • 记下服务账号文件中 GVAClientID (client_id)、GVAClientEmail (client_email)、GVAPrivateKey (private_key)、GVAPrivateKeyID (private_key_id) 和 GVAProjectID (project_id) 的值。

启用 Alexa 异步消息传输并获取 Alexa 消息传输客户端的详细信息

为了获取 Works with Alexa 认证，应当确保系统主动向 Alexa 报告设备状态，因此需启用异步消息。

部署 Alexa Skill 集成，需要启用 Alexa 异步消息传输，并复制 AlexaClientId 和 AlexaClientSecret 字段。详细步骤如下：

  1. 登录 Alexa 开发者控制台。

  2. 选择您在前面步骤中创建的 Smart Home Skill。

  3. 在左侧导航栏中打开 Permissions 选项卡，启用 Send Alexa Events 选项。

Enable Send Alexa Events

  1. 启用 Send Alexa Events 选项后，您将会看到 Alexa Skill Messaging 模块。

  2. 记下 Alexa Client Id 和 Alexa Client Secret 的值。

Alexa App Client

部署 Alexa Smart Home Skill 和 Google Smart Home Actions

  • 此步骤将部署 lambda 函数，该函数用于处理 Alexa 和谷歌语音助手的指令。

部署 ESP-RainMaker-3P-Integrations 堆栈

  • 前往 AWS 控制台，搜索 "Serverless Application Repository" 或 "SAR"。请确保选择的 AWS 区域为 us-east-1。
  • 打开 Private applications 并勾选复选框 Show apps that create custom IAM roles or resource policies。

SAR Private Applications

  • 搜索并点击打开 ESP-RainMaker-3P-Integrations。

Search ESP-RainMaker-3P-Integrations

  • 您将看到 ESP-RainMaker-3P-Integrations 堆栈的部署页面，如下图所示：

ESP-RainMaker-3P-Integrations SAR deployment

  • 输入在 获取 RainMaker API 终端节点 URL 小节中记下的 RainMaker 后端 API 终端节点 URL (APIEndPointURL)。Alexa 和谷歌语音助手处理程序将使用此 URL 与 RainMaker 后端进行通信。

  • 为您的产品输入 Manufacturer Name、Product Description 和 Scene Description 字段。Manufacturer Name 字段的内容将显示给所有通过您的应用连接的场景和产品。填写 Product Description 和 Scene Description 字段时，应向用户描述产品的所有设备和场景。

  • 输入在前面小节中记下的客户端 ID 和 Secret，用于为用户获取 Alexa 刷新令牌。向 Alexa 报告状态时需要使用该刷新令牌。

  • 输入 RainMaker 的部署地区 (RainMakerRegion)。

  • 输入在前面小节中记下的 Alexa Skill ID。

  • 按照在上一步中从服务账号密钥文件中所复制的内容，输入 GVA 报告状态证书字段（GVAClientEmail、GVAClientId、GVAPrivateKey、GVAPrivateKeyID、GVAProjectID）。

  • 勾选复选框并点击 Deploy。

ESP-RainMaker-3P-Integrations successful deployment

  • 部署将持续 5-10 分钟。

在 Alexa 中需要配置 多区域部署 以支持所有地区的调用。

  • 由于在 Alexa 中需要配置多区域部署，因此，您需要将 ESP-RainMaker-3P-Integrations 堆栈部署至另外两个区域。在其他地区部署 ESP-RainMaker-3P-Integrations SAR 时，只需要 Alexa 相关参数，参数值与 us-east-1 地区使用的相同。您需要在以下两个地区部署 ESP-RainMaker-3P-Integrations SAR 仓库：

  • US West 2 (Oregon)

  • EU West 1 (Ireland)

  • 在 Google Actions 中不需要配置多区域部署，只需将其部署在 us-east-1 区域。将 ESP-RainMaker-3P-Integrations 部署至 us-east-1 区域后，Google Actions 也将正确部署在 AWS 中的 us-east-1 区域。

如果您只需部署 Alexa 集成，您可以为 GVAClientEmail、GVAClientID、GVAPrivateKey、GVAPrivateKeyID 和 GVAProjectID 添加一个占位符值，例如 "NA" 或 "To be decided"。此后，若您需要再集成谷歌语音助手，您可以对这些值进行修改。

配置 Alexa Skill 和 Google Actions 控制台的前提条件

获取已部署 Google Actions 的 API 终端节点

  • 前往 AWS 控制台，打开 CloudFormation 并启用 View nested 选项。
  • 搜索 "serverless repo - espgva"。
  • 点击打开堆栈并打开 Outputs 窗格。
  • 记下 GoogleSmartHome 键对应的值，在 Google Actions 控制台中填写 Fulfillment URL 时需要用到该值。

GVA handler Endpoint CFN

获取已部署 Alexa Skill 的 Lambda ARNs

  • 前往 AWS 控制台，打开 CloudFormation 并启用 View nested 选项。
  • 搜索 "serverless repo - espavs"。
  • 点击打开堆栈并打开 Outputs 窗格。
  • 记下 AlexaSmartHome 键对应的值。
  • 在 US East 1 (N. California)、US West 2 (Oregon) 和 EU West 1 (Ireland) 区域分别执行上述步骤。
  • 这些值将成为 Smart Home 服务的终端节点，并被添加至 Alexa 开发者控制台中创建的 Alexa Skill。

Alexa lambda ARN CFN

获取域名 URL

  • 前往 AWS 控制台，打开 Cognito 服务页面，点击 rainmaker-user-pool。
  • 在 App Integration 下，点击 Domain。
  • 复制域名的完整 URL。
  • 记下该值，后续步骤中需要使用。

为 Alexa Skill 和 Google Actions 获取客户端 ID 和 Secret

  • 在 AWS 搜索栏中搜索并打开 Cognito。

Cognito Search

  • 在 Your User Pools 窗格下，点击 rainmaker-user-email-mobile-pool。

Rainmaker Userpool

  • 在 rainmaker-user-pool 中，点击左边导航栏中的 App clients。

App Clients

App Clients1

  • 记下 esp-rainmaker-alexa-skill 和 esp-rainmaker-google-action 应用客户端的 App Client ID 和 App Client Secret（点击 Show Details 后可见）。

开发者控制配置

完成上述所有步骤并记下所有需要的值后，您就可以在 Alexa 和谷歌语音助手开发者控制台中继续进行配置。

后续的配置步骤，请参考：

← 苹果登录Alexa →