Amazon QuickSight BIOps – 第3部分：使用API部署资产

概述

随着商业智能（BI）生态系统在团队、账户和环境间扩展，保持一致性、可靠性和治理成为重大挑战。在多账户环境中，手动部署仪表板和数据集可能导致版本不一致、依赖关系断裂和运营风险增加。

本系列文章聚焦Amazon QuickSight中的商业智能运营（BIOps）。第1部分提供了版本控制和协作的无代码指南，第2部分讨论了使用QuickSight API实现自动版本控制、回滚以及BI资产的持续集成/持续交付（CI/CD）管道。本文重点介绍QuickSight中利用API的BIOps策略，特别涵盖以下主题：

• 使用API跨账户和多环境部署资产
• 数据集版本更新时的冲突检测与解决
• 管理开发、QA和生产环境间的权限和配置

使用Assets-as-Bundle API、Describe-Definition API和自动化脚本等工具，说明如何以编程方式自动部署资产，最大限度减少手动操作并防止下游故障。

解决方案概述

本系列第2部分讨论了使用QuickSight API进行版本控制、回滚和CI/CD工作流。本文在此基础上介绍扩展部署并确保不同环境间一致性的实用技术。以下部分概述基于API的BIOps解决方案，展示团队如何使用程序代码自动化BI资产的部署和治理。讲解在多个AWS账户和区域间部署QuickSight BI资产的方法，说明如何使用API一致、安全且可扩展地部署仪表板、数据集及依赖项。

先决条件

完成本教程需满足以下前提条件：

• AWS账户
• 访问以下AWS服务：
  • AWS CloudFormation
  • Amazon QuickSight
  • Amazon Simple Storage Service (Amazon S3)
• 拥有访问IAM、QuickSight模板、Assets-as-Bundle、Create、Update、Delete、Describe API的权限
• Python基础知识（使用Python 3.9或更高版本）
• SQL基础知识
• 已安装最新版AWS Command Line Interface (AWS CLI)
• 已安装Boto3

建议在继续阅读前先查看本系列的第1部分和第2部分。

资产部署的模板API

在“BIOps: Amazon QuickSight object migration and version control”中，讨论了使用基于模板的方法部署QuickSight资产。撰写本文时，模板是在环境间迁移和备份仪表板的主要手段。

假设有一个开发环境和一个生产环境的两个QuickSight账户，两个账户均配置为连接到有效数据源。下图展示了此架构：

![架构图]

如有兴趣了解实现细节，请参阅原文。但目前不建议使用模板方式进行资产部署。随着Assets-as-Bundle和Describe-Definition等新API的引入，BI团队现在可以利用更灵活、透明且适合版本控制的选项来管理QuickSight资产。

使用Assets-as-Bundle API进行资产批量部署

在“Automate and accelerate your Amazon QuickSight asset deployments using the new APIs”中，讨论了使用Assets-as-Bundle API在AWS账户和区域间部署QuickSight资产的方法。这些API专为部署具有依赖关系的资产（如仪表板、分析、数据集等）而设计。

下图展示了基于此方法的示例工作流：

![工作流图示]

ExportAssetsBundle API提供两种导出格式选项：QuickSight JSON或CloudFormation模板。选择QuickSight JSON选项时，资产将导出为ZIP文件，其中包含对应各资产类型（分析、仪表板、数据集、数据源等）的JSON文件。此ZIP包保留资产间关系，且易于检查和修改单个JSON文件，因此适合部署自动化，但不适合细粒度版本控制。

内容按以下截图所示的层次结构组织：

![内容结构截图]

此示例Jupyter Notebook提供了使用ExportAssetsBundle和ImportAssetsBundle API以QuickSight JSON格式从源账户向目标账户部署QuickSight资产的工作流。此示例适用于基本用例，并可扩展为包含源控制集成、版本标记和环境特定配置步骤的全面部署管道。

资产部署中的权限管理

默认情况下，导出的QuickSight资产不保留用户级或组级权限，除非在导出操作时显式启用include-permissions选项。即使包含权限，如果源环境和目标环境中的用户名或组名不匹配，也可能无法在账户间正确映射。

为实现适当的访问控制，最佳实践是在导入作业完成后使用相应的UpdatePermissions API手动更新资产访问权限。这可确保目标环境中的正确用户或组能够访问导入的仪表板、分析、数据集和其他资产。

另一种选择是使用StartAssetBundleImportJob API的OverridePermissions参数在导入时分配权限。可指定需要授予导入资产访问权限的目标账户用户或组。但需谨慎使用此选项，因为导入作业完成后，指定用户或组将立即能够访问资产。为确保敏感仪表板和数据集不会意外暴露给未经授权的用户，必须确认权限设置正确。

使用环境特定配置管理资产部署

StartAssetBundleImportJob API还提供名为OverrideParameters的参数，BI团队可使用它在导入时覆盖环境特定配置。这包括Virtual Private Cloud (VPC)连接、数据源凭据和其他部署特定属性。

使用OverrideParameters可确保导入到新账户或环境的资产连接到正确的基础设施资源，而无需直接修改导出的捆绑文件。这在环境间（例如从开发环境升级到生产环境）提升资产时特别有用，因为网络或认证设置可能不同。

有关跨环境和账户部署资产的更全面架构，请参阅“Guidance for Multi-Account Environments on Amazon QuickSight”。该指南说明了开发、验证和生产账户的系统管理、QuickSight命名空间和权限管理以及自动化资产部署管道的实现，同时考虑企业系统所需的治理和可扩展性要求。

下图展示了此选项的解决方案架构：

![解决方案架构图]

Assets-as-Bundle API的CloudFormation模板选项在功能上与QuickSight JSON选项相似。选择此选项时，导出输出为CloudFormation模板，封装了仪表板或分析及其依赖项（数据集、数据源、主题、文件夹等）。此选项对已使用AWS CloudFormation进行基础设施自动化的团队特别有用，因为他们可以使用一致的工具和部署管道来部署和管理QuickSight资产及其他AWS资源。

作为实践示例，请参阅展示使用Assets-as-Bundle API的CloudFormation模板选项的一系列工作流的示例Jupyter Notebook。此笔记本演示了如何使用CloudFormation模板在账户间导出和部署QuickSight资产，实现结构化且可重复的资产升级。

下表比较了使用CloudFormation模板与QuickSight JSON (Assets-as-Bundle API)的方法：

有关Assets-as-Bundle API中可用的QuickSight JSON和CloudFormation模板选项的详细比较，请参阅“Choosing between the two export options of the Amazon QuickSight asset deployment APIs”。本文详细说明了每个选项的优缺点，并提供实际示例，帮助BI团队选择最适合其部署工作流和自动化需求的格式。

在“Automate your Amazon QuickSight assets deployment using the new Amazon EventBridge integration”中，讨论了如何将Assets-as-Bundle API与Amazon EventBridge集成以自动化部署工作流。通过设置响应QuickSight资产创建、更新、删除等事件的EventBridge规则，团队可以自动触发在环境间导出、版本控制和升级资产的工作流。此集成对于实现QuickSight BI资产的事件驱动CI/CD管道特别有用。

使用Describe-Definition API进行资产渐进式部署

本系列第2部分讨论了使用Describe-Definition API在单个QuickSight账户内进行版本控制。将相同原则扩展到多账户配置，可以在整个环境中实现BI资产的系统和选择性部署。

在许多场景中，使用Describe API部署单个资产被视为最佳实践。例如，执行生产账户中数据集问题修复的紧急部署而不更新相关仪表板，或更新仪表板内的过滤器定义而不影响依赖资产。这种细粒度控制有助于降低部署风险、避免不必要覆盖，并与大规模BI环境中的渐进式开发工作流保持一致。

有关示例代码，请参阅“BIOps: Amazon QuickSight object migration and version control”，其中说明了两套关于QuickSight资产部署的自动化选项。本文最初基于模板方法，但基本概念至今仍有用。

可以重用和应用相关GitHub仓库中提供的代码。通过将传统模板相关的API调用更新为新的DescribeDashboardDefinition和其他Describe-Definition API，可以扩展相同的自动化工作流，以符合当前关于版本控制资源部署的最佳实践。

API方法比较

下表比较了Assets-as-Bundle API与Describe-Definition API的使用：

备份、恢复和灾难恢复

本节讨论如何使用QuickSight API执行BI资产的备份、恢复和灾难恢复，实现可靠的灾难恢复并最小化环境间的数据丢失。

可以使用Assets-as-Bundle API和Describe-Definition API进行QuickSight资产的备份、恢复和灾难恢复。通过定期将资产导出为捆绑包（ZIP文件或CloudFormation模板）或单个JSON定义，BI团队可以创建版本控制的备份，存储在Amazon S3、Git或其他仓库中。

使用Assets-as-Bundle API，团队可以按仪表板组织备份，将每个仪表板及其依赖项（数据集、数据源、主题等）一起导出。此方法方便且适合按仪表板恢复。

另一方面，Describe-Definition API更灵活但需要更多工作。BI团队可以单独列出所有资产，按类型（数据源、数据集、分析）存储，并维护模块化备份结构。为确保可靠恢复，必须按依赖关系感知的正确顺序重新部署资产，从数据源开始，然后是数据集、主题，最后是仪表板和分析。

如前所述，“BIOps: Amazon QuickSight object migration and version control”文章提供了使用基于模板的方法备份和恢复QuickSight账户资产的示例实现。相关Jupyter Notebook说明了如何自动化整个账户中资产的批量导出和导入。

虽然最初围绕模板构建，但通过将相关API调用替换为Describe-Definition API，可以创建符合当前最佳实践的可扩展且可维护的备份和恢复工作流。

此外，团队可以使用QuickSight文件夹组织备份，将相关资产分组作为结构化恢复策略的一部分，从而更直观地管理恢复操作。有关基于文件夹的备份和恢复方法，请参阅此示例Jupyter Notebook，其中展示了如何导出和重新导入按文件夹组织的QuickSight资产，使BI团队能够将相关资产（仪表板、分析、数据集）分组并进行批量管理。

解决数据集和仪表板间的合并冲突

本节讨论如何在QuickSight中检测和解决数据集与仪表板间的合并冲突，确保模式更改不会破坏依赖的可视化或过滤器。下图展示了数据集版本控制和冲突解决工作流：

![冲突解决工作流图]

此过程从初始数据集 (v1) 开始，评估是否发生了字段重命名或数据类型更改等更新。检测到更新后，数据集升级到版本2 (v2)，并检查潜在合并冲突。如果发现冲突，则判断是否可以通过字段映射（例如，重新映射重命名字段以恢复可视化）解决。如果冲突可解决，则应用映射以恢复受影响资产。如果不可解决（例如，由于数据类型更改），可以使用示例代码自动检测更改的字段，并清理因未解决更改而损坏的过滤器或可视化。

用于检测和处理数据集合并冲突的示例代码可在此Jupyter Notebook中获取。此笔记本演示了如何自动识别更改的字段，解决简单映射问题（如字段数据类型更改），并清理因不兼容更改而损坏的过滤器。

此外，还提供了用于在更新QuickSight数据集时自动化合并冲突检测的示例代码和GitHub Actions工作流。Python脚本compare_quicksight_datasets.py比较数据集版本，以识别数据类型更改、字段名更改、字段添加和字段删除。

GitHub Actions工作流compare-quicksight.yml自动触发执行比较。比较结果存储为仓库中的新构件，BI团队可以审查更改，并决定在提升数据集版本时是自动解决冲突还是手动干预。

要设置和运行工作流，请完成以下步骤：

1. 确保YAML文件保存在正确的GitHub目录中。仓库结构应如下所示：

1
2
3
4
5
6

your-repo/
├── .github/
│   └── workflows/
│       └── compare-quicksight.yml 
├── compare_quicksight_datasets.py 
├── ...

2. 确保compare-quicksight.yml包含有效的触发器，如下例所示：

1
2
3

name: Compare QuickSight Datasets 
on:
  workflow_dispatch:  # 允许手动触发

3. 此方式允许从Actions选项卡手动运行工作流。

4. 将工作流文件提交并推送到仓库：

1
2
3

git add .github/workflows/compare-quicksight.yml 
git commit -m "Add QuickSight dataset comparison workflow"
git push origin main

5. 添加GitHub仓库机密：

   • 转到GitHub仓库，选择Settings > Secrets and variables > Actions。
   • 选择New repository secret。
   • 添加以下机密：
     • AWS_ACCESS_KEY_ID
     • AWS_SECRET_ACCESS_KEY
     • AWS_REGION
     • QUICKSIGHT_ACCOUNT_ID
     • NEW_DATASET_ID

6. 运行工作流：

   • 转到GitHub仓库。
   • 在Actions选项卡中，选择Compare QuickSight Datasets。
   • 选择Run workflow，并提供所需的输入信息。

此实用程序可用作版本控制或部署管道的一部分。此外，BI团队可以通过在分析或仪表板中直接审查和更新受影响的可视化或过滤器来手动解决冲突。

资源删除

为防止未来产生费用，请删除测试期间创建的S3存储桶、QuickSight数据集、分析、仪表板以及示例脚本使用的其他资源。

总结

QuickSight API功能为管理大规模BI资产实现了强大的自动化、治理和灵活性。本文讨论了如何使用API进行跨账户和多环境部署、冲突检测和治理。利用本文指南，可以建立可靠且考虑冲突的QuickSight部署方法。

作者简介

Ying Wang是AWS Generative AI组织的Senior Specialist Solutions Architect，专注于Amazon QuickSight和Amazon Q，支持大型企业和ISV客户。拥有扎实的数据架构师和软件开发工程经理经验，并在数据分析和数据科学领域拥有16年经验。作为数据架构师，帮助客户设计和扩展云上的企业数据架构解决方案。作为工程经理，从工程和产品角度推动新功能交付和产品创新，使客户能够通过QuickSight释放数据力量。