本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 Amazon Cognito 和 iaC 自动化将 Amazon Quick Sight 视觉组件嵌入到网络应用程序中 *Amazon Web Services 的 Ishita Gupta、Saurabh Singh 和 Srishti Wadhwa* ## Summary 这种模式提供了一种专门的方法，通过使用注册用户嵌入和简化的 Amazon Cognito 身份验证，将 Amazon Quick Sight 视觉组件嵌入到 React 应用程序中。然后通过基础设施即代码 (IaC) 模板部署这些资源。与传统的仪表板嵌入不同，该解决方案隔离了特定的图表和图形，以便直接集成到React应用程序中，从而极大地提高了性能和用户体验。 该架构在 Amazon Cognito 用户管理和 Quick Sight 权限之间建立了高效的身份验证流程：用户通过 Amazon Cognito 进行身份验证，并根据 Quick Sight 中的控制面板共享规则访问其授权的可视化效果。这种简化的方法无需直接访问 Quick Sight 控制台，同时还能保持强大的安全控制。 整个环境通过单一模板进行部署，该 AWS CloudFormation 模板配置了所有必要的基础架构组件，包括： + 使用 AWS Lambda 和 Amazon API Gateway 的无服务器后端 + 通过亚马逊 CloudFront、亚马逊简单存储服务 (Amazon S3) Semple Service 和 AWS WAF + 使用 Amazon Cognito 进行身份管理 所有组件均按照安全最佳实践进行配置，包括最低权限 AWS Identity and Access Management (IAM) 策略、 AWS WAF 保护和 end-to-end加密。 该解决方案非常适合希望将安全的交互式分析集成到其应用程序中，同时保持对用户访问权限的精细控制的开发团队和组织。该解决方案使用 AWS 托管服务和自动化来简化嵌入流程、增强安全性并确保可扩展性，以满足不断变化的业务需求。 目标受众和用例： + 想要将分析嵌入到 React 应用程序中的@@ **前端开发者** + 想要提供按用户或基于角色的数据可@@ **视化的软件即服务 (SaaS) 产品团队** + 有兴趣将 AWS 分析集成到自定义门户中的@@ **解决方案架构师** + **商业智能 (BI) 开发人员**，他们希望向经过身份验证的用户展示视觉效果而无需完全访问控制面板 + 想要在内部工具中嵌入交互式 Quick Sight 图表的@@ **企业团队** ## 先决条件和限制 **先决条件** 要成功实现此模式，请确保满足以下条件： + A@@ **ctiv** e AWS 账户 AWS 账户 — 有权部署 CloudFormation 堆栈和创建 Lambda、API Gateway、Amazon Cognito CloudFront 和 Amazon S3 资源。 + **Amazon Quick Sight 账户** — 一个活跃的 Quick Sight 账户，其中至少有一个包含视觉效果的控制面板。有关设置说明，请参阅[教程：使用 Amazon Quick 文档中的示例数据创建 Amazon Quick Sight 控制面板](https://docs.aws.amazon.com/quicksuite/latest/userguide/example-analysis.html)。 + **开发环境**包括： + Node.js（版本 16 或更高版本） + 安装了 npm 或纱线 + Vite 作为 React 构建工具 + React（版本 19.1.1） + **仪表板共享** — 仪表板必须在 Quick Sight 中共享，并且实现者必须登录才能访问嵌入式视觉对象或仪表板。 **限制** + 此模式使用注册用户嵌入方法，该方法要求实现者拥有有效的 Quick Sight 帐户。 + 仅限于与实现此模式的经过身份验证的 Quick Sight 用户明确共享的仪表板和视觉对象。如果实现者没有正确的访问权限，则嵌入网址生成将失败，视觉效果将无法加载。 + CloudFormation 堆栈必须部署在支持 Quick Sight、API Gateway 和 Amazon Cognito AWS 区域 的地方。有关区域可用性，请参阅[按区域划分的AWS 服务](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。 **产品版本** + [快速瞄准嵌入 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 版本 2.10.1 + [React](https://www.npmjs.com/package/react) 版本 19.1.1 + [Node.js](https://nodejs.org/en/download) 版本 16 或更高版本，以确保与本解决方案中使用的最新 React 和 Vite 版本兼容 ## 架构 **目标架构** 下图显示了此模式的架构和工作流。 ![将 Quick Sight 视觉效果嵌入 React 应用程序的架构和工作流程。](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/images/pattern-img/75ad12b1-caaa-4532-b709-8f3eaf3f9cc0/images/d0905f61-9055-49cf-887d-f46f5ca6c871.png) 在此工作流程中： 1. **用户访问应用程序。**用户使用浏览器打开 React Web 应用程序。请求被路由到 CloudFront 分发，该分发充当应用程序的内容交付网络。 1. **AWS WAF 过滤恶意请求**。 ****在请求到达之前 CloudFront，它就会通过 AWS WAF。 AWS WAF 根据安全规则检查流量并阻止任何恶意或可疑的请求。 1. **亚马逊 S3 提供静态文件**。如果请求是干净的，则使用原始访问控制 (OAC) 从私有 S3 存储桶中 CloudFront 检索静态前端资产（HTML、JS、CSS），然后将其交付给浏览器。 1. **用户登录**。应用程序加载完毕后，用户通过 Amazon Cognito 登录，Amazon Cognito 会对用户进行身份验证并返回安全 JSON 网络令牌 (JWT)，用于授权的 API 访问。 1. **应用程序发出 API 请求**。登录后，React 应用程序对 API Gateway 上的`/get-embed-url`端点进行安全调用，并在请求标头中传递 JWT 令牌进行身份验证。 1. **令牌已通过验证**。API Gateway 使用亚马逊 Cognito 授权机构验证令牌。如果令牌有效，则请求继续执行；否则，请求会被拒绝，并返回 401（未授权）响应。 1. **该请求被定向到 Lambda 进行处理。**然后，经过验证的请求会被转发到后端 Lambda 函数。此函数负责为请求的 Quick Sight 视觉效果生成嵌入网址。 1. **Lambda 从 Quick Sight 生成嵌入网址**。IAM 使用具有适当权限的 IAM 角色调用 Quick Sight `GenerateEmbedUrlForRegisteredUser` API 来生成安全的、用户范围的可视化网址。 1. **Lambda 将嵌入网址返回到 API** Gateway。作为 JSON 响应的一部分，Lambda 将生成的嵌入网址发送回 API Gateway。然后准备好将该响应传送到前端。 1. **嵌入的 URL 将发送到浏览器**。嵌入网址作为 API 响应返回给浏览器。 1. **视觉效果将显示给用户**。 ****React 应用程序接收响应并使用 Quick Sight Embedding SDK 向用户呈现特定的视觉效果。 **自动化和扩展** 后端和前端部署完全自动化 CloudFormation，使用在单个部署中预置所有必需的 AWS 资源，包括 Amazon Cognito、Lambda、API Gateway、A CloudFront mazon S3 AWS WAF、、、、IAM 角色和 CloudWatch 亚马逊。 这种自动化可确保在所有环境中实现一致且可重复的基础架构。所有组件都会自动扩展：Lambda 会根据函数调用进行调整，在全球范围内 CloudFront 提供缓存内容，API Gateway 可根据传入的请求进行扩展。 ## 工具 **AWS 服务** + [Amazon Quick Sight](https://aws.amazon.com/quicksuite/quicksight/) 是一项云原生商业智能服务，可帮助您创建、管理和嵌入交互式仪表板和视觉对象。 + [Amazon API Gateway](https://aws.amazon.com/api-gateway/) 管理着它 APIs 充当 React 应用程序和后端服务之间的桥梁。 + [AWS Lambda](https://aws.amazon.com/lambda/)是一种无服务器计算服务，这种模式使用它来生成安全的 Quick Sight URLs 动态嵌入，并根据请求自动扩展。 + [Amazon Cognito](https://aws.amazon.com/cognito/) 为用户提供身份验证和授权，并为 API 访问颁发安全令牌。 + [Amazon S3](https://aws.amazon.com/s3/) 托管这种模式的静态前端资产，并通过 CloudFront安全的方式为它们提供服务。 + [Amazon](https://aws.amazon.com/cloudfront/getting-started/) 以低延迟在全球范围内 CloudFront 提供前端内容，并与之集成 AWS WAF 以进行流量过滤。 + [AWS WAF](https://aws.amazon.com/waf/)通过应用安全规则和速率限制来保护 Web 应用程序免受恶意流量的侵害。 + [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)可在单个部署中自动配置和配置所有应用程序资源。 + [亚马逊](https://aws.amazon.com/cloudwatch/)从 Lambda、API Gateway CloudWatch 收集日志和指标， AWS WAF 用于监控和故障排除。 **开发工具** + [React JS](https://react.dev/) 是一个前端框架，这种模式使用它来构建 Web 应用程序和集成嵌入式 Quick Sight 视觉效果。 + [Vite](https://vite.dev/) 是一种构建工具，用于快速开发和优化 React 应用程序的生产构建。 + Qu@@ [ick Sight Embedding SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk/v/2.10.1) 有助于将 Quick Sight 视觉效果嵌入 React 应用程序，并实现应用程序和视觉效果之间的无缝交互。 **代码存储库** 此模式的代码可在 [React 存储库中的 GitHub Amazon Quick Sight Visual Embedding 中](https://github.com/aws-samples/sample-quicksight-visual-embedding)找到。 ## 最佳实践 此模式会自动实现以下安全最佳实践： + 使用 Amazon Cognito 用户池进行基于 JWT 的身份验证，以及可选的多因素身份验证 (MFA)。 + APIs 使用 Amazon Cognito 授权机构进行保护，并在所有服务中强制执行最低权限 IAM 政策。 + 实现 Quick Sight 注册用户嵌入，并自动为用户配置读者角色。 + 通过 CloudFront 和 HTTPS 强制执行支持 TLS 1.2 及更高版本的传输中加密。 + 使用带版本控制和 OAC 的 Amazon S3 的 AES-256 对静态数据进行加密。 + 使用限制和配额配置 API Gateway 使用计划。 + 使用预留并发性和环境变量保护来保护 Lambda。 + 启用 Amazon S3 CloudFront、Lambda 和 API Gateway 的日志记录；使用监控服务。 CloudWatch + 加密日志、应用访问控制，并对非 HTTPS 或未加密的上传强制执行拒绝策略。 此外，我们建议采取以下措施： + CloudFormation 用于自动化部署并在不同环境中保持一致的配置。 + 确保每个用户都具有访问嵌入式视觉效果的正确的 Quick Sight 权限。 + 使用 Amazon Cognito 授权者保护 API Gateway 终端节点，并对所有 IAM 角色强制执行最低权限原则。 + 将诸如 Amazon 资源名称 (ARNs) 和环境变量之类的敏感信息存储 IDs 在环境变量中，而不是对其进行硬编码。 + 通过减少依赖关系和提高冷启动性能来优化 Lambda 函数。有关更多信息，请参阅 AWS 博客文章 “[优化 AWS Lambda 使用高级启动策略的冷启动性能](https://aws.amazon.com/blogs/compute/optimizing-cold-start-performance-of-aws-lambda-using-advanced-priming-strategies-with-snapstart/)”。 SnapStart + 将您的 CloudFront 域名添加到 Quick Sight 许可名单，以启用安全的视觉嵌入。 + 使用和进行日志、警 AWS WAF 报 CloudWatch 和流量保护来监控性能和安全性。 **其他推荐的最佳做法** + 使用带有 SSL 证书的自定义域名， AWS Certificate Manager 以提供安全和品牌化的用户体验。 + 使用客户托管 AWS Key Management Service (AWS KMS) 密钥加密 Amazon S3 数据和 CloudWatch 日志，以便更好地控制加密。 + 使用地理封锁、SQL 注入 (SQLi)、跨站脚本 (XSS) 保护和自定义过滤器来扩展 AWS WAF 规则，以增强威胁防御。 + 启用 CloudWatch 警报 AWS Config、和， AWS CloudTrail 以实现实时监控、审计和配置合规性。 + 应用精细的 IAM 策略，强制执行 API 密钥轮换，并仅在绝对必要时才允许跨账户访问。 + 定期进行安全评估，确保与合规框架保持一致，例如系统和组织控制2 (SOC 2)、《通用数据保护条例》(GDPR) 和《健康保险流通与责任法案》(HIPAA)。 ## 操作说明 ### 准备环境 | Task | 说明 | 所需技能 | | --- | --- | --- | | 克隆存储库。 | 将此解决方案的 GitHub 存储库克隆到您的本地系统并导航到项目目录：
git clone https://github.com/aws-samples/sample-quicksight-visual-embedding.git

cd sample-quicksight-visual-embedding

该存储库包含部署解决方案所需的 CloudFormation 模板和 React 源代码。 | 应用程序开发人员 | ### 部署堆 CloudFormation 栈 | Task | 说明 | 所需技能 | | --- | --- | --- | | 部署 模板。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) 有关更多信息，请参阅 CloudFormation 文档中的[创建和管理堆栈](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacks.html)。 | AWS 管理员 | | 监控堆栈创建。 | 在 “**事件**” 选项卡中监控堆栈，直到其状态为 **CREATE\_** COMPLETE。 | AWS 管理员 | | 检索堆栈输出。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | AWS 管理员 | ### 配置前端环境 | Task | 说明 | 所需技能 | | --- | --- | --- | | 检索快速视觉标识符。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | 快速瞄准管理员 | | 配置你的本地 React 环境。 | 要设置本地 React 环境并将其链接到 AWS 资源，请在本地 GitHub 存储库的`my-app/`文件夹中创建一个`.env`文件。在文件中填充以下内容：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html)
以下是一个示例`.env`文件：
VITE_AWS_REGION=us-east-1

# Cognito Configuration (from CloudFormation outputs)
VITE_USER_POOL_ID=us-east-1_xxxxxxxxx VITE_USER_POOL_WEB_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx

# API Configuration (from CloudFormation outputs)
VITE_API_URL=https:/your-api-id.execute-api.us-east-1.amazonaws.com/prod

# QuickSight Visual Configuration
VITE_DASHBOARD_ID=your-dashboard-id 
VITE_SHEET_ID=your-sheet-id 
VITE_VISUAL_ID=your-visual-id
| 应用程序开发人员 | ### 设置用户身份验证 | Task | 说明 | 所需技能 | | --- | --- | --- | | 在 Cognito 中创建或管理用户 | 要允许经过身份验证的用户访问嵌入式 Quick Sight 视觉对象，您需要先在 Amazon Cognito 中创建用户：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | AWS 管理员 | | 提供快速查看仪表板访问权限 | 要提供对 Quick Sight 视觉效果的访问权限，请向经过身份验证的用户提供查看者权限访问权限：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html)
每位用户都将收到一封包含仪表板链接的电子邮件。您可以随时通过 “**共享**” 菜单修改权限。
有关更多信息，请参阅 [Amazon Quick Sight 文档中的授予个人 Amazon Quick Sight 用户和群组访问 Amazon Quick Sight 中控制面板](https://docs.aws.amazon.com/quicksuite/latest/userguide/share-a-dashboard-grant-access-users.html)的权限。 | 快速瞄准管理员 | ### 构建和部署 React 前端 | Task | 说明 | 所需技能 | | --- | --- | --- | | 安装依赖关系并生成项目。 | 在 React 应用程序目录中，运行以下命令以生成经过优化的生产文件：
cd my-app
npm install
npm run build
| 应用程序开发人员 | | 将构建文件上传到 Amazon S3。 | 将`my-app/dist/`目录中的所有文件上传到由配置的 S3 存储桶 CloudFormation （不要上传文件夹本身）。 | 应用程序开发人员 | | 创建 CloudFront 失效。 | 在[CloudFront 控制台](https://console.aws.amazon.com/cloudfront/v4/home)上，为部署后刷新缓存内容`/*`的路径创建失效。有关说明，请参阅 CloudFront 文档中的[使文件失效](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation_Requests.html)。 | AWS 管理员 | ### 配置 Quick Sight 许可名单 | Task | 说明 | 所需技能 | | --- | --- | --- | | 将该 CloudFront 域名添加到 Quick Sight 许可名单。 | 要使您的 CloudFront 域能够安全地嵌入 Quick Sight 视觉效果，请执行以下操作：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | 快速瞄准管理员 | ### 访问应用程序并验证功能 | Task | 说明 | 所需技能 | | --- | --- | --- | | 打开 React 应用程序。 | 使用**CloudFront 域**（来自 CloudFormation 输出）在浏览器中打开已部署的 React Web 应用程序。 | 应用程序所有者 | | 验证身份验证。 | 使用 Amazon Cognito 凭证登录应用程序，通过 API Gateway 验证身份验证流程和 JWT 验证。 | 应用程序所有者 | | 验证嵌入式视觉效果。 | 确认 Quick Sight 视觉效果是否基于用户特定的访问权限在应用程序中正确加载。 | 应用程序所有者 | | 验证 API 和 Lambda 的连接。 | 确认应用程序可以成功调用 `/get-embed-url` API 并检索有效的 Quick Sight 嵌入内容 URLs 而不会出现错误。 | 应用程序所有者 | ### 监控和维护应用程序 | Task | 说明 | 所需技能 | | --- | --- | --- | | 使用监控 CloudWatch。 | 您可以使用可 AWS 观察性工具来监控应用程序，并在生产中保持安全、可扩展的性能。
查看 Lambda 日志、API Gateway 指标和 Amazon Cognito 身份验证事件 CloudWatch ，以确保应用程序运行状况并检测异常情况。 | AWS 管理员 | | 跟踪 AWS WAF 和 CloudFront 记录。 | 检查 AWS WAF 日志中是否有被阻止或可疑的请求，并检查 CloudFront 访问日志以了解性能和缓存指标。 | AWS 管理员 | ## 问题排查 | 问题 | 解决方案 | | --- | --- | | “域名不允许” 错误 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | | 身份验证错误 | 可能的原因：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html)
解决方案：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | | API Gateway 错误 | 可能的原因：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html)
解决方案：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | | Quick Sight 视觉效果无法加载 | 可能的原因：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html)
解决方案：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | | “用户无权访问” 错误 | 可能的原因：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html)
解决方案：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/embed-quick-sight-visual-components-into-web-apps-cognito-iac.html) | ## 相关资源 ** AWS 文档** + [注册 Amazon Quick 订阅](https://docs.aws.amazon.com/quicksight/latest/user/signing-up.html) + [亚马逊 Quick Sight 的嵌入式分析](https://docs.aws.amazon.com/quicksuite/latest/userguide/embedded-analytics.html) + [快速瞄准 API 参考 — GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html) + [Amazon Cognito 用户群体](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html) + [AWS Lambda 开发人员指南](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) + [亚马逊 API Gateway 开发者指南](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) + [基本监控和详细监控 CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html) + [AWS CloudFormation 用户指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) + [亚马逊 CloudFront 开发者指南](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) + [AWS WAF 开发人员指南](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) **教程和视频** + [亚马逊 Quick Sight 的嵌入式分析](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics.html) + [Amazon 快速瞄准 YouTube 教程](https://www.youtube.com/results?search_query=amazon+quicksight+embedding)