本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在 Amazon Quick Sight 嵌入式控制面板和视觉对象的运行时筛选数据
<a name="embedding-runtime-filtering"></a>

您可以在 Amazon Quick Sight 嵌入软件开发工具包中使用筛选方法，在运行时在软件即服务 (SaaS) 应用程序中利用 Amazon Quick Sight 筛选器的强大功能。运行时筛选器允许企业主将其应用程序与嵌入式 Amazon Quick Sight 仪表板和视觉效果集成。为此，请在应用程序中创建自定义筛选条件控件，并根据应用程序中的数据应用筛选条件预设。然后，开发人员可以在运行时为最终用户个性化筛选条件配置。

开发人员可以使用 Amazon Quick Sight Embedding SDK 在嵌入式控制面板上创建、查询、更新和移除 Amazon Quick Sight 筛选条件，或者从应用程序中移除视觉效果。使用[FilterGroup](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_FilterGroup.html)数据模型在您的应用程序中创建 Amazon Quick Sight 筛选对象，并使用筛选方法将其应用于嵌入式仪表板和视觉对象。有关使用 Amazon Quick Sight 嵌入软件开发工具包的更多信息，请参阅[amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)上的 GitHub。

**先决条件**

在开始之前，请确保您使用的是 Amazon Quick Sight Embedding SDK 版本 2.5.0 或更高版本。

## 术语和概念
<a name="runtime-filtering-terminology"></a>

使用嵌入式运行时筛选时，以下术语可能很有用。
+ *筛选条件组* – 一组单独的筛选条件。位于 `FilterGroup` 内的筛选条件彼此之间进行 OR 运算。中的筛选[FilterGroup](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_FilterGroup.html)器应用于相同的工作表或视觉对象。
+ *筛选条件* - 单个筛选条件。筛选条件可以是类别、数字或日期时间筛选条件类型。有关筛选条件的更多信息，请参阅[筛选条件](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_Filter.html)。

## 设置
<a name="runtime-filtering-setup"></a>

开始之前，请确保您已准备好以下资产和信息。
+ 您想要将 `FilterGroup` 范围限定到的工作表的工作表 ID。这可以通过 Embedding SDK 中的 `getSheets` 方法获取。
+ 您想要筛选的数据集和数据集的列标识符。这可以通过 [DescribeDashboardDefinition](https://docs.aws.amazon.com/APIReference/API_DescribeDashboardDefinition.html)API 操作获得。

  根据您使用的列类型，可以添加到嵌入式资产的筛选条件类型可能会受到限制。有关筛选条件限制的更多信息，请参阅 [Filter](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_Filter.html)。
+ 如果适用，则为要将 `FilterGroup` 范围限定到的视觉对象的视觉对象 ID。这可以使用 Embedding SDK 中的 `getSheetVisuals` 方法获取。

  除了 `getSheetVisuals` 方法之外，您添加的 `FilterGroup` 只能限于当前选定的工作表。

要使用此功能，您必须已经通过 Amazon Quick Sight Embedding SDK 将仪表板或视觉效果嵌入到应用程序中。有关使用 Amazon Quick Sight 嵌入软件开发工具包的更多信息，请参阅[amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)上的 GitHub。

## SDK 方法接口
<a name="runtime-filtering-sdk-interface"></a>

**控制面板嵌入 getter 方法**

下表介绍了开发人员可以使用的不同控制面板嵌入 getter 方法。


| 方法 | 说明 | 
| --- | --- | 
|  `getFilterGroupsForSheet(sheetId: string) `  |  返回当前限 FilterGroups 定为参数中提供的表单的所有内容。  | 
|  `getFilterGroupsForVisual(sheetId: string, visualId: string)`  |  返回范围限定为参数中提供的视觉对象的所有 `FilterGroups`。  | 

如果参数中提供的工作表不是嵌入式控制面板中当前选定的工作表，则上述方法会返回错误。

**视觉对象嵌入 getter 方法**

下表介绍了开发人员可以使用的不同视觉对象嵌入 getter 方法。


| 方法 | 说明 | 
| --- | --- | 
|  `getFilterGroups()`  |  返回范围当前限定为嵌入式视觉对象的所有 `FilterGroups`。  | 

**Setter 方法**

下表介绍了开发人员可用于控制面板或视觉对象嵌入的不同 setter 方法。


| 方法 | 说明 | 
| --- | --- | 
|  `addFilterGroups(filterGroups: FilterGroup[])`  |  将提供的内容添加并应用**FilterGroups**到嵌入式仪表板或视觉对象。返回 `ResponseMessage` 指示添加是否成功。  | 
|  `updateFilterGroups(filterGroups: FilterGroup[])`  |  更新嵌入式体验上与参数中提供的 `FilterGroup` 包含相同 `FilterGroupId` 的 `FilterGroups`。返回 `ResponseMessage` 指示更新是否成功。  | 
|  `removeFilterGroups(filterGroupsOrIds: FilterGroup[] \| string[])`  |   FilterGroups 从仪表板中移除提供的内容，并返回 a，`ResponseMessage`表示删除尝试是否成功。  | 

提供的 `FilterGroup` 的范围必须限定于当前选定的嵌入式工作表或视觉对象。