本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在執行時間篩選 Amazon Quick Sight 內嵌儀表板和視覺效果的資料
<a name="embedding-runtime-filtering"></a>

您可以使用 Amazon Quick Sight 內嵌 SDK 中的篩選方法，在執行時間利用軟體即服務 (SaaS) 應用程式內的 Amazon Quick Sight 篩選功能。執行期篩選條件可讓企業擁有者將其應用程式與內嵌的 Amazon Quick Sight 儀表板和視覺效果整合。若要達成此目的，請在應用程式中建立自訂篩選條件控制項，並根據應用程式的資料套用篩選預設。然後，開發人員可以在執行時期為最終使用者個人化篩選條件組態。

開發人員可以使用 Amazon Quick Sight 內嵌 SDK，在內嵌儀表板或視覺效果上建立、查詢、更新和移除 Amazon Quick Sight 篩選條件。使用 [FilterGroup](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_FilterGroup.html) 資料模型在應用程式中建立 Amazon Quick Sight 篩選物件，並使用篩選方法將其套用至內嵌儀表板和視覺效果。如需使用 Amazon Quick Sight 內嵌 SDK 的詳細資訊，請參閱 GitHub 上的 [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

**先決條件**

開始使用之前，請確定您使用的是 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。這可透過「嵌入式 SDK」中的 `getSheets` 方法取得。
+ 您要篩選之資料集的資料集與資料欄識別碼。這可透過 [DescribeDashboardDefinition](https://docs.aws.amazon.com/APIReference/API_DescribeDashboardDefinition.html) API 操作取得。

  根據您使用的資料欄類型，可能會限制可新增至嵌入式資產的篩選條件類型。如需有關篩選條件限制的詳細資訊，請參閱[篩選條件](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_Filter.html)。
+ 您想要將 `FilterGroup` 的範圍限定在其中的視覺效果的 ID (如適用)。這可以透過使用「嵌入式 SDK」中的 `getSheetVisuals` 方法取得。

  除了 `getSheetVisuals` 方法之外，只能將您新增之 `FilterGroup` 的範圍限定在目前選取的工作表。

若要使用此功能，您必須已透過 Amazon Quick Sight Embedding SDK 將儀表板或視覺效果內嵌至您的應用程式。如需使用 Amazon Quick Sight 內嵌 SDK 的詳細資訊，請參閱 GitHub 上的 [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

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

**儀表板嵌入 getter 方法**

下表說明開發人員可以使用的不同儀表板嵌入 getter 方法。


| Method | Description | 
| --- | --- | 
|  `getFilterGroupsForSheet(sheetId: string) `  |  傳回目前範圍限定在參數中提供之工作表的所有 FilterGroups。  | 
|  `getFilterGroupsForVisual(sheetId: string, visualId: string)`  |  傳回範圍限定在參數中提供之視覺效果的所有 `FilterGroups`。  | 

如果參數中提供的工作表不是嵌入式儀表板目前選取的工作表，上述方法會傳回錯誤。

**視覺效果嵌入 getter 方法**

下表說明開發人員可以使用的不同視覺效果嵌入 getter 方法。


| Method | Description | 
| --- | --- | 
|  `getFilterGroups()`  |  傳回目前範圍限定在嵌入式視覺效果的所有 `FilterGroups`。  | 

**Setter 方法**

下表說明開發人員可用於儀表板或視覺效果嵌入的不同 Setter 方法。


| Method | Description | 
| --- | --- | 
|  `addFilterGroups(filterGroups: FilterGroup[])`  |  將提供的 **FilterGroups** 新增並套用到嵌入式儀表板或視覺效果。會傳回表明新增項目是否成功的 `ResponseMessage`。  | 
|  `updateFilterGroups(filterGroups: FilterGroup[])`  |  更新嵌入式功能上的 `FilterGroups`，其中包含與參數中提供的 `FilterGroup` 相同的 `FilterGroupId`。會傳回表明更新是否成功的 `ResponseMessage`。  | 
|  `removeFilterGroups(filterGroupsOrIds: FilterGroup[] \| string[])`  |  從儀表板移除提供的 FilterGroups，並傳回表明移除嘗試是否成功的 `ResponseMessage`。  | 

提供的 `FilterGroup` 之範圍必須限定在目前選取的嵌入式工作表或視覺效果。