跳到主要内容

概述

本指南介绍了如何使用 AWS SAM 和 CloudFormation StackSets 部署集成第三方的堆栈，从而集成 Alexa/GVA 和 RainMaker。关键集成内容包括：为 Alexa 和谷歌创建的 Cognito 应用客户端、处理语音助手指令的 Lambda 函数，以及满足认证要求的必要附加组件。

组件说明​

该部署主要包括以下堆栈：

  1. 为 Alexa 和 GVA 创建的 AWS Cognito 应用客户端（ESP-RainMaker-3p-CognitoClients）

    • 创建用于 Alexa skill 和 Google Action 的 AWS Cognito 应用客户端。

  2. Alexa Smart Home Skill 和谷歌 Smart Home Action 在三个区域的部署（ESP-RainMaker-3P-Integrations）

    • 部署处理来自 Alexa 和谷歌语音助手指令的 Lambda 函数。

  1. Alexa Smart Home Skill 和 Google Action 的附加扩展模块

    • Google Action：附加模块仓库提供了一个 webhook 处理器，用于主动将节点状态的变更报告至谷歌的 HomeGraph 数据库。详情请参考 Google Smart Home Action 报告状态。必须实现主动报告功能才能通过 Google Action 的认证。

    • Alexa skill：附加模块仓库提供了用于设置 Alexa App-to-App 账号关联的 API 端点。App-to-App 账号关联允许用户从自有应用开始完成账号绑定。详情请参考 Alexa App-to-App 账号关联。必须实现此关联才能为产品获得 Works with Alexa (WWA) 认证。

      WWA 认证与 Alexa skill 的认证与发布不同。

    • 只有实现上述功能才能通过 Alexa Skill (WWA) 和 Google Action (WWGA) 认证，因此必须部署附加模块仓库。

准备工作​

ESP-RainMaker-3p-CognitoClients​

  1. 请确保已按照 Cognito 域名配置指南中的步骤创建了 Cognito 域名。

    RainMaker Dashboard Domain Name

  2. 记录身份提供商的信息。

    • 进入 RainMaker 管理面板，在左侧导航栏点击 Deployment Settings 选项卡，获取 RainMaker 部署中已配置的身份提供商列表。
    • 然后点击 Identity Providers 选项卡。
    • 记下列出的身份提供商信息。
    • 如果配置了 Google、GitHub 和 SignInWithApple，那么在部署 ESP-RainMaker-3p-CognitoClients 的 SAR 应用时，SkillIdentityProviders 的对应值应为 Google, GitHub、SignInWithApple 和 COGNITO。

      如果未配置任何身份提供商，则默认值仅为 COGNITO。

    RainMaker Dashboard IDP List

  3. 按照 Alexa skill 创建步骤，记录 AlexaCognitoCallbackURLs 和 SkillId。

  4. 按照 Google Action 创建步骤，记录 GVACallbackURLs。

ESP-RainMaker-3P-Integrations​

  • Alexa 和 GVA 处理器会调用 RainMaker 的 API 接口以获取设备信息。因此，在部署 ESP-RainMaker-3P-Integrations 应用时，需要提供 RainMaker API 的地址。
  • 请按照获取 RainMaker API（基础 URL）中的步骤获取 RainmakerAPIUrl。
  • RainMaker 后端 API 接口地址格式为：<RainmakerAPIUrl>/v1/。
  • 请记录此值，它将在下一步作为 APIEndPointURL 使用。

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

GVA 处理程序将主动向谷歌云的 HomeGraph 服务报告设备状态，因此你需要创建一个谷歌服务账号，并将该账号添加至处理程序中。

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

  1. 在账号中启用 HomeGraph API。以下为详细步骤：

    • 前往谷歌 HomeGraph 主页。
    • 在顶部下拉菜单中，选择在前几步中创建的智能家居项目。
    • 点击 Enable.

  2. 创建服务账号密钥文件.

    • 前往谷歌服务账号主页。
    • 选择在前几步中创建的智能家居项目。
    • 点击 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 消息传输客户端的详细信息​

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

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

  • 登录 Alexa 开发者控制台。

  • 选择在前面步骤中创建的 Smart Home Skill。

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

    Enable Send Alexa Events

  • 启用 Send Alexa Events 选项后，你将会看到 Alexa Skill Messaging 模块。

  • 记下 Alexa Client Id 和 Alexa Client Secret 的值。

    Alexa App Client

部署步骤​

部署 Alexa 和 GVA 语音集成组件时，将使用 CloudFormation 的多区域 StackSet（堆栈集），此过程将部署以下模块：

  • ESP-RainMaker-3p-CognitoClients
  • ESP-RainMaker-3P-Integrations-Addons
  • ESP-RainMaker-3P-Integrations（部署区域：us-east-1、eu-west-1、us-west-2）

  1. 进入 AWS 管理控制台

    • 在服务菜单中搜索 "CloudFormation" 并点击进入。

    SAR22

  2. 创建 Stackset

    • 在 CloudFormation 服务中点击 Create StackSet。

    SKILLS1

  3. 选择 IAM 角色

    • 所需的 IAM 角色将自动创建。选择相应的角色并点击 Next。
      • 管理员角色名：esp-AWSCloudFormationStackSetAdminRole
      • 执行角色名：esp-AWSCloudFormationStackSetExecutionRole

    SKILLS3

  4. 选择模板

    • 按照指南创建 S3 URL 模板。

    SKILLS2

  5. 输入 Stack 名称

    • 输入堆栈名称：ESP-3P-Integrations-Skills-Add-Ons

    SKILLS4

  6. 填写输入参数

    • 提供 Alexa 和 GVA 集成所需的输入参数。各参数说明可参考对应模块部分。

    SKILLS5 SKILLS6

    • 点击 Next 继续。
    参数名称描述
    AlexaCognitoCallBackUrls可参考创建 Alexa Smart Home Skill 一节获取该值。
    GVACognitoCallBackUrls可参考创建谷歌 Smart Home Action 一节获取该值。
    SkillIdentityProvidersNewUserPool输入在创建 AWS Cognito 应用客户端 一节中记录的身份提供商。
    SkillIdentityProviders保持默认值。如果配置了 Google、GitHub 和 SignInWithApple，则对应值应为 Google, GitHub、SignInWithApple 和 COGNITO。
    APIEndPointURL在获取 API 接口地址 一节中记录的 RainMaker 后端 API 地址，将由 Alexa 和 GVA 的处理程序用于与 RainMaker 后端进行通信。
    AlexaClientID之前记录的 Alexa 客户端 ID，用于获取用户的 Alexa refresh token。
    AlexaClientSecret之前记录的 Alexa 客户端密钥。
    AlexaSkillID之前记录的 Alexa skill ID。
    RainMakerRegion输入 RainMaker 所部署的区域（如：us-east-1）。
    ManufacturerName输入产品的制造商名称，此名称将在所有通过你应用连接的场景和产品中可见。
    ProductDescription输入产品描述。
    SceneDescription输入与你产品相关的场景描述。
    GVAClientID来自服务账号的谷歌客户端 ID，需从密钥文件中复制。
    GVAClientEmail来自服务账号的谷歌客户端邮箱，需从密钥文件中复制。
    GVAPrivateKey来自服务账号的谷歌私钥，需从密钥文件中复制。
    GVAPrivateKeyID来自服务账号的谷歌私钥 ID，需从密钥文件中复制。
    GVAProjectID来自服务账号的谷歌项目 ID，需从密钥文件中复制。

  7. 添加标签

    • 添加版本标签：
      • Key：Version
      • Value：<VERSION>（请替换为你选择的版本）
    • 点击 Add new tag 添加新标签，其他设置保持默认，点击 Next。

    CFVERSION

  8. 输入账号 ID 并选择部署区域

    • 将 <ACCOUNT_ID> 替换为你的 AWS 账号 ID。
    • Alexa 需要多区域部署 以支持全球用户调用，因此请选择以下区域：
      • 美国东部 (us-east-1, N. Virginia)
      • 美国西部 (us-west-2, Oregon)
      • 欧洲西部 (eu-west-1, Ireland)
    • 如果你的 RainMaker 部署区域不同，请从下拉菜单中选择正确的区域。

    SKILLS8

  9. 检查并创建

    • 勾选以下选项：
      • I acknowledge that AWS CloudFormation might create IAM resources.（我确认 AWS CloudFormation 可能会创建 IAM 资源。）
      • I acknowledge that AWS CloudFormation might create IAM resources with custom names.（我确认 AWS CloudFormation 可能会创建自定义命名的 IAM 资源。）
      • I acknowledge that AWS CloudFormation might require the capability: CAPABILITY_AUTO_EXPAND.（我确认 AWS CloudFormation 可能需要 CAPABILITY_AUTO_EXPAND 权限。）
    • 点击 Create StackSet 创建堆栈集。

    SKILLS9

  10. 等待部署完成

    • 等待所有选定区域中的堆栈集部署完成，整个过程大约需要 15～20 分钟。

    SKILLS10

On this page