使用 QuickSight 嵌入式 SDK 中的新运行时功能构建自定义和互动仪表板商业智能博客

2026-01-27 13:04:22
经典案例

利用 QuickSight 嵌入 SDK 创建自定义互动仪表板

关键要点

在这篇文章中，我们介绍了 Amazon QuickSight 嵌入 SDK 的新功能，允许开发者在运行时动态更新嵌入式仪表板的主题和过滤器。这一功能使您能够在 SaaS 应用程序中无缝集成 QuickSight 的嵌入式仪表板并提供个性化的用户体验。

Amazon QuickSight 是一种完全托管的云原生商业智能BI服务，您可以用它连接到数据并创建可与数千用户共享的互动仪表板。这些仪表板可以在 QuickSight 内部使用，也可以嵌入在软件即服务SaaS应用中。

使用 QuickSight 嵌入式 SDK 中的新运行时功能构建自定义和互动仪表板商业智能博客

今天，我们推出了一项功能，您可以通过 QuickSight 嵌入 SDK 在运行时动态更新嵌入式仪表板和可视化的主题和过滤器。运行时过滤和主题更新将帮助您轻松将 SaaS 应用程序集成到 QuickSight 嵌入式仪表板和可视化中。您现在可以使用嵌入 SDK 中的新方法来：

利用过滤器方法在 SaaS 应用程序中运用 QuickSight 过滤器的强大功能，实现与嵌入式 QuickSight 仪表板和可视化的无缝集成。您还可以在应用程序中创建自定义过滤器控件，根据应用程序中的数据应用过滤预设，并为用户个性化过滤配置信息。使用新功能同步嵌入内容的主题与父应用程序，解锁个性化和可访问性选项。用户可以在运行时应用预配置的主题，或更新仪表板视图的默认主题。

功能概述

要动态更新嵌入仪表板和可视化的主题和过滤器，您需要使用 QuickSight 嵌入 SDK 版本 250 或更高版本。

运行时过滤

您可以使用嵌入 SDK 创建、查询、更新和移除嵌入仪表板或可视化中的 QuickSight 过滤器。使用 FilterGroup 数据模型在应用程序中创建 QuickSight 过滤器对象，并通过过滤器方法将其应用于嵌入式仪表板和可视化。

设置方法：方法说明getFilterGroupsForSheet(sheetId)返回当前作用于指定表单的 FilterGroups。getFilterGroupsForVisual(sheetId visualId)返回作用于指定可视化的 FilterGroups。addFilterGroups(filterGroup[])向嵌入式仪表板或可视化添加并应用指定的 FilterGroups。updateFilterGroups(filterGroup[])使用提供的 FilterGroup 更新具有相同 FilterGroupId 的嵌入体验。removeFilterGroups(filterGroup[] filterGroupId[])从仪表板中移除指定的 FilterGroups。

运行时主题

您可以在运行时更改 QuickSight 嵌入仪表板和可视化的主题。这些主题更改可以在仪表板和可视化的初始化阶段和使用期间进行。当设置主题的 Amazon 资源名称 (ARN) 时，用户必须有访问该主题的权限。这可以通过分析编辑器的主题列表中的共享选项完成，或使用 UpdateThemePermissions API。

设置方法：方法说明setTheme(themeArn string)用另一个主题替换仪表板或可视化的当前主题。setThemeOverride(themeOverride ThemeConfiguration)在当前主题上设置动态的 ThemeConfiguration。使用主题初始化

通过在 DashboardContentOptions 和 VisualContentOptions 中指定 theme ARN，可以用非仪表板设置的主题来初始化嵌入式 QuickSight 仪表板和可视化。

javascriptconst frameOptions = { url ltYOUREMBEDURLgt container #yourcontainer}const contentOptions = { theme arnawsquicksightawstheme/RAINIER}const embeddedDashboardExperience = await embeddingContextembedDashboard(frameOptions contentOptions)

用例

AnyCompany Inc 是一家虚构的独立软件供应商ISV，在多个地区运营，客户遍布各个行业，包括企业、初创公司和中小型企业SMB。AnyCompany 拥有来自这些不同客户的数千名用户访问他们的应用程序门户。AnyCompany 希望在其 SaaS 应用程序中为北美和欧洲的用户提供定制、个性化和可访问的体验，包括嵌入分析。它们的用例主要围绕着 SaaS 应用程序中的嵌入分析内容，并希望根据用户所处的身份和要查看的信息动态个性化用户体验。这个新功能还允许 AnyCompany 用户在嵌入仪表板中选择和保存他们喜欢的主题为默认主题，从而在登录嵌入式仪表板时展示用户偏好的主题内容。

运行时主题

ISV 拥有各种客户，需要将他们使用的 SaaS 应用程序的外观和感觉与其应用程序无缝融合，包括匹配公司色彩方案和主题。AnyCompany 也有类似的需求，需要满足其客户在将 QuickSight 仪表板嵌入到其 SaaS 应用程序中的要求。它们在样式和主题方面有多种选择，很多情况下，AnyCompany 将开发一个单一仪表板，必须以多种主题、颜色和字体进行呈现。

明亮模式与暗黑模式

AnyCompany 的 SaaS 应用程序提供多种主题和色彩方案供其用户选择，其中最常见的用法是切换门户的明亮模式与暗黑模式。当在 SaaS 应用程序级别切换明亮模式与暗黑模式时，AnyCompany 希望嵌入的内容与父应用程序保持同步。

例如，当应用程序在默认模式下加载时，网站使用经典默认或明亮主题，如下图所示。

当用户切换到午夜主题时，整个体验变为暗黑模式。

为了实现这一点，AnyCompany 现在使用最新的运行时主题功能，并且可以根据用户的选择在运行时加载主题。

javascriptfunction UpdateTheme(themeId) { awsDataembeddedDashboardExperiencesetTheme(arnawsquicksightawstheme/ themeId)}

用户偏好主题

AnyCompany 允许其 SaaS 应用程序的用户按用户级别自定义用户体验。这意味着每个用户都可以选择和保存他们的主题偏好，以便每次登录时都加载。主题偏好由 AnyCompany 存储，并在运行时传递给嵌入 SDK。

下图显示了 NorthUser 定义的偏好主题，这在 NorthUser 登录门户时自动加载。

vps加速器下载

javascriptlet themeArn = arnawsquicksightawstheme/CLASSIC if(userName == NorthUser) themeArn = arnawsquicksightawstheme/RAINIER} const frameOptions = { url embedUrl container #dashboardContainer width 100 height 100 withIframePlaceholder true onChange function(event) { LogEvent(DASHBOARDCHANGEEVENT event) } Dummy dummy}const contentOptions = { locale enUS toolbarOptions { export false undoRedo false reset false } themeArn themeArn onMessage function(event) { LogEvent(DASHBOARDMESSAGEEVENT event) }}

字体自定义

AnyCompany 还希望根据每个客户或用户的需求，从 QuickSight 提供的字体中加载和更改字体。为此，AnyCompany 使用 themeOverride 选项来覆盖字体设置。通过使用此选项，AnyCompany 可以更新和自定义当前主题的字体设置。

下图展示了 AnyCompany 现在能够通过 themeOverride 选项更改嵌入仪表板上的字体、背景和数据颜色。

javascriptfunction UpdateFont(fontId) { awsDataembeddedDashboardExperiencesetThemeOverride(JSONparse({Typography{FontFamilies[{FontFamily fontId }]}))}

function UpdateColorScheme(colorId) { if(colorId == Teal) colorId = {DataColorPalette {Colors [#117A8B#22D475#8A50B3#7FD4B9#F65D6A#4263A6#3D993D#E673C9]MinMaxGradient [#CCF0FF#29A8DD]EmptyFillColor #F6F7F8}} else if(colorId == Navy) colorId = {DataColorPalette {Colors [#00558C#F9B218#8A50B3#7FD4B9#F65D6A#4263A6#3D993D#E673C9]MinMaxGradient [#CCF0FF#29A8DD]EmptyFillColor #F6F7F8}} else colorId = {DataColorPalette {Colors [#FF5050#FF743A#FF9014#FFC301#FAFF01#FBFF77#FDFFC3#FEFFF9]MinMaxGradient [#FF0000#FF7C00]EmptyFillColor #F6F7F8}}

awsDataembeddedDashboardExperiencesetThemeOverride(JSONparse(colorId))

}

运行时过滤

自定义过滤器控件： AnyCompany 利用此功能在其 SaaS 应用程序中创建自定义过滤器控件，应用基于应用程序的数据的过滤预设，并为个体用户个性化过滤配置。例如，他们为不同的用户角色展示不同的过滤器控件，并希望添加更多动态控件以与仪表板和底层数据集互动。

过滤预设和个性化配置：

AnyCompany 的 SaaS 应用程序展示与用户地理区域相关的财务数据，并根据国家和地区进行过滤。AnyCompany 希望使用预设过滤器根据每个用户的国家和地区在上下文中呈现更多嵌入内容。根据每个用户在 SaaS 应用程序其他部分的选择和偏好，AnyCompany 希望个性化嵌入内容的视图。预设允许 AnyCompany 添加多个具有不同值和控件的过滤器。

以下示例展示了在 PowerUser 登录该应用程序时，页面外部存在一个过滤器控件。用户可以与控件互动以过滤仪表板中的数据。该过滤器不是由作者创建的，而是在应用程序加载时动态创建的。这使开发者能够基于每个用户的需求和访问权限提供自定义用户体验。

而当 NorthUser 登录应用程序时，他们并未看到区域过滤器，且无法进一步与数据互动。

javascriptconst customerregionfiltergroupid = customerregionfiltergroupid// 获取当前选择的表单 IDconst selectedSheetId = await awsDataembeddedDashboardExperiencegetSelectedSheetId()// 获取所选表单的当前可视化const visualsForSelectedSheet = await awsDataembeddedDashboardExperiencegetSheetVisuals(selectedSheetId)

var visuals = new Array()visualsForSelectedSheetforEach((element) =gt visualspush(element[VisualId]))

// 获取选定选项的当前值const selectedValues = eventvar arr = new Array() arrpush(selectedValues)const categoryValues = arr // 检查仪表板中 FilterGroup 是否已存在const sheetFilterGroups = await awsDataembeddedDashboardExperiencegetFilterGroupsForSheet(selectedSheetId)const existingCategoryFilterGroup = sheetFilterGroupsfind((filterGroup) =gt { return filterGroupFilterGroupId === customerregionfiltergroupid})

// 否则就在仪表板上创建并添加一个新的 FilterGroupif (!existingCategoryFilterGroup) { const categoryFilterGroup = { Status ENABLED Filters [ { CategoryFilter { Configuration { CustomFilterListConfiguration { NullOption NONNULLSONLY MatchOperator CONTAINS CategoryValues categoryValues } } Column { ColumnName Customer Region DataSetIdentifier Business Review } FilterId customerregionfilterid } } ] CrossDataset SINGLEDATASET ScopeConfiguration { SelectedSheets { SheetVisualScopingConfigurations [ { Scope SELECTEDVISUALS SheetId selectedSheetId VisualIds visuals } ] } } FilterGroupId customerregionfiltergroupid }// 将 FilterGroup 添加到仪表板 awsDataembeddedDashboardExperienceaddFilterGroups([categoryFilterGroup])} else {// 获取现有 FilterGroup，并使用新选择的值更新 CategoryFilter const updatedCategoryFilter = { existingCategoryFilterGroup Filters [ { CategoryFilter { existingCategoryFilterGroupFilters[0]CategoryFilter Configuration { CustomFilterListConfiguration { NullOption NONNULLSONLY MatchOperator CONTAINS CategoryValues categoryValues } } } } ] }// 更新仪表板上的现有 FilterGroup await awsDataembeddedDashboardExperienceupdateFilterGroups([updatedCategoryFilter])}

结论

运行时过滤和嵌入仪表板以及可视化的主题更新可以帮助您轻松将 SaaS 应用程序与 QuickSight 嵌入式仪表板和可视化集成。本文介绍了如何应用这些新方法实现与嵌入 SDK 的无缝集成。

如果您有任何问题或反馈，请留下评论。如需进一步讨论和获取解答，请访问 QuickSight 社区。

加入 QuickSight 社区，与其他人互动、回答问题和学习，并探索更多资源。

作者介绍

Mayank Agarwal 是 Amazon QuickSight 的产品经理，专注于嵌入分析和开发者体验。他的职业生涯始于嵌入式软件工程师，开发手持设备。进入 QuickSight 前，他在 Credence ID 领导工程团队，开发使用 AWS 服务的定制移动嵌入式设备和 Web 解决方案，为政府部门、医疗保健和交易安全应用提供快速、直观和经济高效的生物特征注册和身份识别服务。

Srikanth Baheti 是 Amazon QuickSight 的全球专业首席解决方案架构师。他的职业生涯始于顾问工作，为多个私人和政府组织工作。随后他在 PerkinElmer Health 和 eResearch Technology Inc 工作，负责设计和开发高流量 Web 应用程序，以及使用 AWS 服务和无服务器计算搭建高度可扩展和可维护的数据管道。

Raji Sivasubramaniam