目次
Target Contents
2023年8月4日に行われた Amazon QuickSight Roadshow 東京に参加しました。Dive Deep Session のテーマとなった QuickSight のアセット管理、データセットパラメーターに関する内容を執筆します。
Event Infomation
本編に入る前にイベントの状況を少しお伝えします。本イベントは終日開催のオフラインイベントとなっており、大勢の方が参加されておりました。アジェンダは以下のリンクにある通り進行されておりました。
https://poweredbyquicksight-tokyo.splashthat.com/
QuickSight に関するアップデート情報から、QuickSight を活用した取り組み、Dive Deep Session 、Sagemaker Canvas との連携、注目の Generative BI といった非常に豊富なコンテンツを現地で聞く事が出来ました。
今回は冒頭の通り、 Dive Deep Session でのアセット管理、データセットパラメーターについて、講演頂いた内容を元に検証した結果を執筆致します。
Dive Deep Session - Asset Management -
QuickSight のアセット管理では、用途と目的に沿って、いくつかのパターンがあります。QuickSight Dive Deep Session では、パターン毎にご説明がありましたので、検証を含めてまとめていきます。
Asset Management Pattern Summary
Session 内で公開された、アセット管理のために利用される Template , AaC , AaB に関するサマリーです。セッションの最後に投影されたため、評価、用途を理解した上で使用するものと感じました。撮影がうまくいかず少し見づらいですが、完結にまとまっており、非常に分かりやすいものとなってます。
ここから検証を踏まえて一つずつパターンを解釈していきます。
Asset Management Pattern - Template -
QuickSight ではテンプレートと呼ばれる定義が存在します。これは、分析の作成に必要なデータをカプセル化し、分析の依存関係にあるデータセットを置き換えることにより、アセットの抽象化を行います。
テンプレートは、移行をするための主な活用ケースとして利用されるかと思いますが、Template ワークフローとして以下のような手順となるようです。
実際に検証をしてみます。Create-Template API を使用するために必要な分析、データセットのArn を Describe から取得します。 あるいはいずれも DatasetId か AnalysisId から構成されていますので、QuickSight 画面のURLから取得も可能です。その後、Create-Template を JSON ファイルから呼び出すために例えば以下のような記述のJSONを用意します。
{
"AwsAccountId": "xxxxx",
"TemplateId": "template20230806",
"Name": "template1",
"SourceEntity": {
"SourceAnalysis": {
"Arn": "arn:aws:quicksight:ap-northeast-1:xxxxxxxx:analysis/8bcc9900-30f6-4283-8a00-1009dfc0497a",
"DataSetReferences": [
{
"DataSetPlaceholder": "test-template-placeholder",
"DataSetArn": "arn:aws:quicksight:ap-northeast-1:xxxxxxxx:dataset/ac853ffe-aa69-49c3-a5b1-d37484ca0eaf"
}
]
}
}
}
Create-Template コマンドを実行し、正常に処理が完了したかを Describe-template コマンドを使用して確認します。
aws quicksight describe-template --aws-account-id <account-id> --template-id template20230806 {
"Status": 200,
"Template": {
"Arn": "arn:aws:quicksight:ap-northeast-1:xxxxxxxxx:template/template20230806",
"Name": "template1",
"Version": {
"CreatedTime": "2023-08-06T20:44:46.903000+00:00",
"VersionNumber": 1,
"Status": "CREATION_SUCCESSFUL",
"DataSetConfigurations": [
{
"Placeholder": "test-template-placeholder",
"DataSetSchema": {
"ColumnSchemaList": [
{
"Name": "Staff",
"DataType": "STRING"
},
{
"Name": "Address",
"DataType": "STRING"
},
.
.一部抜粋となりましたが、Template には VersionNumber が付与されています。Template 自体はQuickSight 画面から確認は出来ないものの、バージョン管理がQS単体で行える点はメリットかと思われます。
本来は別アカウントへの移行用途として使用出来るテンプレートですが、検証が難しいため、動作確認は以上となります。ポイントは、定義済のテンプレートを移行アカウントから再現させる場合、Create Template の Permissions オプションから、移行先の Template の呼び出しを許可する必要があるかと思いますので、ここは注意が必要です。
アカウントではなく、テナントレベルでの Template に関しては、以下が構成が分かりやすいものとなっておりました。
参考: セットアップイメージ
Asset Management Pattern - Asset As Code(AaC) -
Asset As Code は、describe-analysis-definition API を利用し、主に分析の可視化された画面をコード化する点がポイントと考えられます。以下は AaC に関する内容です。
参考: BI トランスフォーメーションを加速する Amazon QuickSight API の新機能
describe-analysis-definition API では、分析をJSON形式へコード出力をする事が出来ます。これを活用し、コードレベルでのアセット管理を実現します。検証実装を以下に記載していきます。
まず、既存の分析を使用します。これは一般的な分析画面です。後続作業に必要なのは AnalysisId であり、デフォルトでは分析画面のURLの末尾にある英数字から構成されるものです。
続いて describe-analysis-definition API を呼び出します。先ほどのAnalysisIdを指定し、JSON形式で出力します。
aws quicksight describe-analysis-definition --aws-account-id <account-id> --analysis-id <analysis-id> > test-analysis.json
JSON の中身を見てみましょう。JSON コードは非常に長いコードで管理されるため、一部抜粋しています。
{
"Status": 200,
"AnalysisId": "8bcc9900-30f6-4283-8a00-1009dfc0497a",
"Name": "test-analysis",
"ResourceStatus": "CREATION_SUCCESSFUL",
"ThemeArn": "arn:aws:quicksight::aws:theme/MIDNIGHT",
"Definition": {
"DataSetIdentifierDeclarations": [
{
"Identifier": "test-dataset using test-analysis",
"DataSetArn": "arn:aws:quicksight:ap-northeast-1:xxxxxx:dataset/ac853ffe-aa69-49c3-a5b1-d37484ca0eaf"
}
],
"Sheets": [
{
"SheetId": "287e47f5-2d50-44d2-9c86-d2aed5c5fb87",
"Name": "シート 1",
"ParameterControls": [
{
"Dropdown": {
"ParameterControlId": "4ffe3c01-f8fb-44ad-93a2-5fd0bb9e30b6",
"Title": "Section1",
"SourceParameterName": "Section",
"DisplayOptions": {
"SelectAllOptions": {
"Visibility": "VISIBLE"
},
"TitleOptions": {
"Visibility": "VISIBLE",
"FontConfiguration": {
"FontSize": {
"Relative": "MEDIUM"
}
}
}
},
"Type": "SINGLE_SELECT",
"SelectableValues": {
"LinkToDataSetColumn": {
"DataSetIdentifier": "test-dataset using test-analysis",
"ColumnName": "Staff "
}
}
}
},
{
"Dropdown": {
"ParameterControlId": "04d37304-983f-40c5-aef9-bfb56ddf1696",
"Title": "Period",
"SourceParameterName": "Period",
"DisplayOptions": {
"SelectAllOptions": {
"Visibility": "VISIBLE"
},
"TitleOptions": {
"Visibility": "VISIBLE",
"FontConfiguration": {
"FontSize": {
"Relative": "MEDIUM"
}
}
}
},
"Type": "SINGLE_SELECT",
"SelectableValues": {
"LinkToDataSetColumn": {
"DataSetIdentifier": "test-dataset using test-analysis",
"ColumnName": "Start Date"
}
}
}
}
]
.
.
.
"RequestId": "xxxxxxxxx"
}Definition key 以降をピックアップします。DataSetIdentifierDeclarations をはじめ、sheets Kety 内部のVisuals Key 、ParameterControls Key などがネストされていることが分かると思います。これが分析のコード化です。
"Definition": {
"DataSetIdentifierDeclarations": [
{
"Identifier": "test-dataset using test-analysis",
"DataSetArn": "arn:aws:quicksight:ap-northeast-1:xxxxxx:dataset/ac853ffe-aa69-49c3-a5b1-d37484ca0eaf"
}
],
"Sheets": [
{
"SheetId": "287e47f5-2d50-44d2-9c86-d2aed5c5fb87",
"Name": "シート 1",
"ParameterControls": [
{
"Dropdown": {
"ParameterControlId": "4ffe3c01-f8fb-44ad-93a2-5fd0bb9e30b6",
"Title": "Section1",
"SourceParameterName": "Section",
"DisplayOptions": {
"SelectAllOptions": {
"Visibility": "VISIBLE"
},
"TitleOptions": {
"Visibility": "VISIBLE",
"FontConfiguration": {
"FontSize": {
"Relative": "MEDIUM"
}
}
}
},
"Visuals": [
{
"TableVisual": {
"VisualId": "4d2dd5ec-7445-4206-bf0a-34125dad7c5e",
"Title": {
"Visibility": "VISIBLE",
"FormatText": {
"RichText": "<visual-title>\n <block align=\"center\">\n <inline font-size=\"16px\">\n <b>Table</b>\n </inline>\n </block>\n</visual-title>"
}
},
"Subtitle": {
"Visibility": "VISIBLE"
},
"ChartConfiguration": {
"FieldWells": {
"TableAggregatedFieldWells": {
"GroupBy": [
{
"NumericalDimensionField": {
"FieldId": "8ddb66e7-fc26-4ece-9243-02bd6e29694c.ColumnId-1.2.1651360683465",
"Column": {
"DataSetIdentifier": "test-dataset using test-analysis",
"ColumnName": "ID"
}
}
},
{
"CategoricalDimensionField": {
"FieldId": "8ddb66e7-fc26-4ece-9243-02bd6e29694c.ColumnId-4.1.1651360680841",
"Column": {
"DataSetIdentifier": "test-dataset using test-analysis",
"ColumnName": "First Name"
}
}
},
.
.続いて、create-analysis API または、update-analysis API を使用します。ここでポイントとなるのは、先ほど出力した JSONの修正点です。例えば、JSONファイルをそのまま create-analysis API 内で使用すると、呼び出しは失敗します。
Create-analysis API の場合、ポイントは Definition key より外出しされている AwsAccountId 、AnalysisId の追加または修正(update-analysis はそのままです)、出力時の Status / Resource Status / RequestId を削除し、AWS CLI オプションと整合性を合わせる必要があります。また、Theme に関しても 分析 Definition とはレイヤ別となると言えます。
{
"AwsAccountId": "xxxxxxx",
"AnalysisId": "testanalysisid20230806",
"Name": "test-analysis",
"ResourceStatus": "CREATION_SUCCESSFUL",
"ThemeArn": "arn:aws:quicksight::aws:theme/MIDNIGHT",再度実行します。実行が成功すると、新たに発行した分析は、共有して表示するユーザーに権限付与を行います。以下の共有画面からわかる事は、分析 Name における 重複は可能、Analysis-id は一意である必要があるという事となります。
では、続いて上記の分析で使用されたデータセットを複製してみましょう。後続作業では、複製したDatasetId が必要となります。URLにある英数字にある一意のIDです。
先ほど出力した JSON に手を加えます。Definition key にネストされた DataSetIdentifierDeclarations の Identifier, DataSetArn これらを複製したデータセットへ変更します。また、他の DataSetIdentifier Key の値を全て複製したデータセット名へ変更します。
"Definition": {
"DataSetIdentifierDeclarations": [
{
"Identifier": "test-dataset using test-analysis-2",
"DataSetArn": "arn:aws:quicksight:ap-northeast-1:xxxxxx:dataset/<DatasetId>"
}再度、JSONを用いて create-analysis-api を実行します。新しく発行した分析の表示権限をユーザーに付与します。
分析を見ると、複製した側のデータセットが分析画面として利用されていることが分かります。
AaC では、describe-analysis-definition API を使用して 可視化された分析画面をJSON形式でコード管理出来る事が分かりました。また、データセットのデータ群が同一あるいは類似のデータセットではあれば、DataSetIdentifierDeclarations Key の変換により置き換えが可能であるという事が分かりました。
分析のJSONコードはQS以外のリポジトリから update-analysis API を使用するためのバージョン管理や、類似データセットの置き換えをアイディアをもって使用出来る事となると思います。他の二つと比較すると、移行向けというより、コード管理あるいはCI/CD向けの内容に近しいものかと感じました。但し、新APIという事もあり、Definition Key 内の記述をコードレベルから変更して、フロントを作成していく作業は、現状ではテクニックが必要となるかと考えます。
Asset Management Pattern - Asset As Bundle(AaB) -
Asset As Bundle は複数のAPIを組み合わせて使用する事で、移行を成立させる点がポイントとなるかと考えられます。
参考: Automate and accelerate your Amazon QuickSight asset deployments using the new APIs
上記のブログに記載があるように、複数の Export / Import API を使用します。具体的に見ていきます。
前提として、同一 QuickSight アカウント上からも動作は確認出来るものです。これは、別の QuickSight アカウントに移行するために利用されるケースが非常に多いかと思いますが、今回は、同一アカウント上から確認します。
はじめに、start-asset-bundle-export-job API を実行します。export-format オプションでは、CLOUDFORMATION_JSON または QUICKSIGHT_JSON を指定します。
aws quicksight start-asset-bundle-export-job --aws-account-id <account-id> --asset-bundle-export-job-id job-1 --resource-arns arn:aws:quicksight:ap-northeast-1:xxxxxxxx:analysis/8bcc9900-30f6-4283-8a00-1009dfc049711111 --export-format QUICKSIGHT_JSON
続いて、describe-asset-bundle-export-job APIを実行します。成功しますと、Dowunloadurl が返りますので、ここから qs ファイルをダウンロードします。最初のブログに記載があるように、エクスポート ジョブの出力は、.qs 拡張子が付いた単一の zip ファイルです。この zip ファイルには、アセット タイプごとに個別のフォルダーが含まれています。このファイル自体に手は加えません。
aws quicksight describe-asset-bundle-export-job --aws-account-id <aacount-id> --asset-bundle-export-job-id job-1
任意のS3バケットへファイルを配置し、QuickSight アカウント上から当該バケットの権限を付与します。
これより start-asset-bundle-Import-job を発行しますが、事前にエクスポートした分析を削除します。qs ファイルから、同一の分析が新たに Import された事により作成された事を確認するためです。ここでは、Base64 エンコード文字列として引き渡すオプションを指定します。
aws quicksight start-asset-bundle-import-job --aws-account-id <account-id> --asset-bundle-import-job-id job-1 --asset-bundle-import-source "{\"S3Uri\": \"s3://xxxxx/assetbundle-job-1.qs\"}" --region ap-northeast-1 --cli-binary-format raw-in-base64-out
最後に describe-asset-bundle-import-job の出力によって、JobStatus が SUCCESSFUL である事を確認します。
aws quicksight describe-asset-bundle-import-job --aws-account-id <account-id> --asset-bundle-import-job-id job-1 --region ap-northeast-1
最後にImport した分析を共有し、削除した分析が見えるか確認します。
Asset As Bundle(AaB) は移行の用途で利用されるケースが多いかと思われますが、ブログに記載があるようにアカウント間の移行で価値を発揮するものと考えます。また、エクスポート対象のアセットはデータセットや分析だけでなく、VPC Connection なども対応しているため、アセット毎に分離した移行を行う、または、Export 時に使用する IncludeAllDependencies オプションを使用して依存関係のあるアセットを全て移行対象とすることも出来ます。
ポイントとなるのは、各アセットの依存関係を上書きするための start-asset-bundle-import-job 実行時の override-parameters オプションです。ここが問題なく成功すれば、移行がスムーズになると考えます。
Dive Deep Session - Dataset Parameter -
続いて Dataset Parameter の Dive Deep Session についてです。分析(Analysis) では、以前よりパラメーターが存在していましたが、2023年5月にデータセット上から Parameter が使用可能となりました。
参考: Amazon QuickSight でのデータセットパラメータの使用
https://docs.aws.amazon.com/ja_jp/quicksight/latest/user/dataset-parameters.html
以下は、データセットパラメーターについて言及している動画となります。非常に分かりやすいため、ここで引用させていただきます。
引用: Amazon QuickSight QuickSight Dataset Parameter: 2023 Amazon QuickSight Learning Series
では、利用ケースについてみていきましょう。
Direct Query on Custom SQL
Custom SQL 上から定義した Dataset Parameter を使用する事が出来ます。これは UDF(User Defined Function) に近しいイメージと捉えています。例えば Athena 上で Lambda 関数をクエリから呼び出すケースなどです。但し、Parameter ですので、一意のValue が定義されているという点が違いかと思います。
CustomSQL の編集画面上から Parameter を選択し、Parameter として定義したい値を指定します。
これをクエリ内に指定する場合、 <<$PamameterName >> を指定する事が可能となります。以下の例では、Where 句の条件として Parameter を使用しています。
また、複数の値を定義する事も可能です。
複数の値が含まれるパラメーターをクエリ内に指定する場合、 (<<$PamameterName >>) を指定する事で利用可能となります。以下の例では、Where 句の条件として Parameter を使用したものをカウントしています。
これらは、Case や IF 関数でも使用する事が出来ます。以下は $hudmaxavgValue の範囲内の値の場合に NULL とし、それ以外の場合に 0.98 の重み付けを行い、それらの値のみを表示させるよう outlier (外れ値) を抽出したものです。データセットに定義が無いものを新たにParameter 化する事でクエリの自由度、あるいは汎用性が高くなることがメリットではないかと思います。
Create Versatile Dataset
本Session のユースケースが挙げられておりました 2番 についてです。
データセットパラメーターは、データセット上の計算フィールドにおいても使用する事が出来ます。これは、先ほどのカスタムSQLとは異なりSPICEデータとして利用が出来ます。
分析のレイヤーからデータセットのレイヤに引き上げする事で汎化されたデータセットを作成する事が出来る点が大きいものと考えます。
非常にシンプルな例ですが、2023Year という DatasetParameter には 2023年という値が入っています。これを使用して計算フィールド 2023 Year を作成します。同様に 2024 Year の計算フィールドを 2024Year Dataset Parameter を使用して追加します。
データセットは 2023年の分析と 2024年の分析を作成します。これを１つのデータセット上から管理する事が出来るといったものです。
なお、上記の例は DatasetParameter が機能追加された事による側面として、メリットが薄いように感じますが、特定の文字列を簡易的にデータセットのレイヤから計算フィールドとして追加する事が出来るようになったという点も大きいかと考えられます。
Dataset Parameter の利用方法として、他にもフィルターや、ドロップダウンコントロールなどを分析で利用するケースなどが挙げられるようで、データセットの汎化以外にも活用方法が多く考えられるようです。ここはもう少し深堀する必要があります。
参考: データセットパラメータの高度なユースケース
https://docs.aws.amazon.com/ja_jp/quicksight/latest/user/dataset-parameters-advanced-options.html
本イベントであったように QuickSight のリリース頻度が高く、今後も多くの機能がリリースされる事を期待しています。
実装の際はAWSドキュメントをご確認の上、ご対応をお願い致します。
この記事をシェアする
