翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Amazon Quick Sight 埋め込みダッシュボードとビジュアルの実行時のデータのフィルタリング
<a name="embedding-runtime-filtering"></a>

Amazon Quick Sight 埋め込み SDK のフィルターメソッドを使用して、実行時に Software as a Service (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 Embedding 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。これは、Embedding 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 (該当する場合)。これは、Embedding SDK の `getSheetVisuals` メソッドを使用して取得できます。

  `getSheetVisuals` メソッドに加えて、追加する `FilterGroup` の範囲は、現在選択されているシートにのみ設定できます。

この機能を使用するには、Amazon Quick Sight Embedding SDK を介してアプリケーションにダッシュボードまたはビジュアルが埋め込まれている必要があります。Amazon Quick Sight Embedding SDK の使用の詳細については、GitHub の [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk) を参照してください。

## SDK メソッドインターフェイス
<a name="runtime-filtering-sdk-interface"></a>

**ダッシュボード埋め込みゲッターメソッド**

次の表には、デベロッパーが使用できるさまざまなダッシュボード埋め込みゲッターメソッドの説明が記載されています。


| 方法 | 説明 | 
| --- | --- | 
| `getFilterGroupsForSheet(sheetId: string) ` | パラメータで指定されたシートに現在範囲設定されているすべての FilterGroup を返します。 | 
| `getFilterGroupsForVisual(sheetId: string, visualId: string)` | パラメータで指定されたビジュアルに範囲設定されているすべての `FilterGroups` を返します。 | 

パラメータで指定されたシートが、埋め込みダッシュボードの現在選択されているシートではない場合、上記のメソッドはエラーを返します。

**ビジュアル埋め込みゲッターメソッド**

次の表には、デベロッパーが使用できるさまざまなビジュアル埋め込みゲッターメソッドの説明が記載されています。


| 方法 | 説明 | 
| --- | --- | 
| `getFilterGroups()` | 埋め込みビジュアルに現在範囲設定されているすべての `FilterGroups` を返します。 | 

**設定メソッド**

次の表には、デベロッパーがダッシュボードまたはビジュアル埋め込みに使用できるさまざまなセッターメソッドの説明が記載されています。


| 方法 | 説明 | 
| --- | --- | 
| `addFilterGroups(filterGroups: FilterGroup[])` | 指定された **FilterGroups** を埋め込みダッシュボードまたはビジュアルに追加して適用します。追加が成功したかどうかを示す `ResponseMessage` が返されます。 | 
| `updateFilterGroups(filterGroups: FilterGroup[])` | パラメータで指定された `FilterGroup` と同じ `FilterGroupId` を含む、埋め込みエクスペリエンスの `FilterGroups` を更新します。更新が成功したかどうかを示す `ResponseMessage` が返されます。 | 
| `removeFilterGroups(filterGroupsOrIds: FilterGroup[] \| string[])` | 指定された FilterGroups をダッシュボードから削除し、削除の試行が成功したかどうかを示す `ResponseMessage` を返します。 | 

指定される `FilterGroup` は、現在選択されている埋め込みシートまたはビジュアルに範囲設定される必要があります。