0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@zumax

QuickSight APIのDefinitionを使ってダッシュボードを作成・更新してみた

0
Posted at

背景・目的

QuickSightのダッシュボードをGUIで作成する場合、ビジュアルの配置や計算式の調整に時間を要することがあります。
QuickSight APIでは Definition というJSON構造でダッシュボード全体を記述でき、コードベースで作成・更新が可能です。

本記事ではDefinition APIの基本操作を試します。

  1. create-dashboard でDefinition JSONからダッシュボードを新規作成
  2. update-dashboard でビジュアルを追加・更新
  3. describe-dashboard-definition で現在のDefinition JSONを取得・確認

まとめ

項目 内容
Definitionとは ダッシュボードの中身（ビジュアル・計算式・フィルタ・レイアウト）を1つのJSONで表現したもの
ChartConfiguration ビジュアルの中身の設定（どのカラムをどこに配置するか、並び順、見た目）
Layouts シート上のビジュアルの位置・サイズを定義。GridLayoutは36カラム構成
create-dashboard Definition JSONを渡してダッシュボードを新規作成。テンプレート不要
update-dashboard Definition JSONを書き換えて既存ダッシュボードを更新。新バージョンが作成される
update-dashboard-published-version 更新後に公開バージョンを切り替える。これをしないとコンソールに反映されない
権限（permissions） CLIで作成したダッシュボードはデフォルトで権限なし。明示的に付与しないとコンソールに表示されない

概要

アセットの階層

QuickSightのアセットは以下の関係になっています。（Terminology and concepts、re:Invent 2022ブログ）

DataSource(接続情報)  
↓
DataSet (列選択・結合)  
↓
Analysis(編集する作業場)
↓
Dashboard(閲覧専用)

GUIで操作するのはAnalysis。Dashboardは共有用の読み取り専用スナップショットです。

Definitionとは

2022年のre:Inventで追加された概念です。（New Amazon QuickSight API Capabilities to Accelerate Your BI Transformation）

ダッシュボードの中身（ビジュアル・計算式・フィルタ・レイアウト）全てを1つのJSONで表現します。（API Reference - DashboardVersionDefinition）

Definition
├── DataSetIdentifierDeclarations[] ← 必須。DataSetへの参照
├── Sheets[]
│   ├── Visuals[]                  ← チャート/テーブルの定義
│   └── Layouts[]                  ← 画面上の位置・サイズ
├── CalculatedFields[]             ← 計算フィールド（式を文字列で定義）
├── FilterGroups[]                 ← フィルター
└── ParameterDeclarations[]        ← パラメータ

ポイント：

  • Definitionの形状はAnalysis / Template / Dashboardで共通
  • テンプレートを作らず、Definition直接指定でcreate-dashboardできる
  • describe-dashboard-definitionで既存のJSONを取得 → 編集 → 反映、が基本フロー

ChartConfiguration

DefinitionからみたときのChartConfigurationは下記のとおりです

Definition
└── Sheets[]
    └── Visuals[]
        └── TableVisual / BarChartVisual / KPIVisual / ...
            └── ChartConfiguration  ← ここ

ChartConfiguration は、ビジュアルの中身の設定を定義するオブジェクトです。

Visual（ビジュアル）
├── VisualId          ← 識別子
├── Title             ← 表示タイトル
└── ChartConfiguration ← ★ここ：何をどう表示するか
    ├── FieldWells     ← どのカラムをどこに配置するか（行/列/値）
    ├── SortConfiguration ← 並び順
    ├── TableOptions   ← 見た目の設定（ヘッダー表示、セル背景色など）
    └── ...

Layouts

Definitionからみたときの Layouts は下記のとおりです

Definition
├── DataSetIdentifierDeclarations[]  ← Definition直下
├── CalculatedFields[]               ← Definition直下
├── FilterGroups[]                   ← Definition直下
├── ParameterDeclarations[]          ← Definition直下
└── Sheets[]                         ← Definition直下
    ├── Visuals[]                    ← Sheet内
    └── Layouts[]                    ← Sheet内※ここ

VisualsとLayoutsは、何を表示するか、どこに配置するかを設定するものです

Definition
└── Sheets[]
    ├── Visuals[]   ← 何を表示するか（中身）
    └── Layouts[]   ← どこに配置するか（位置・サイズ）

Layoutsの例は、下記のとおりです。

"Layouts": [{
    "Configuration": {
        "GridLayout": {
            "Elements": [
                {"ElementId": "table-visual-1", "ColumnSpan": 36, "RowSpan": 12},
                {"ElementId": "kpi-visual-1", "ColumnSpan": 12, "RowSpan": 6}
            ]
        }
    }
}]

実践

前提

  • AWS CLIまたはboto3を使用
  • QuickSight Enterprise Editionを利用
  • リージョン: ap-northeast-1
  • 以前作成したデータセットを使用

データセットの確認

1.　データセットを確認します

aws quicksight list-data-sets \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --region ap-northeast-1

---
{
    "DataSetSummaries": [
        {
            "Arn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dataset/monthly-sales-summary",
            "DataSetId": "monthly-sales-summary",
            "Name": "Monthly Sales Summary",
            "ImportMode": "SPICE"
        }
    ],
    "Status": 200
}

データセットのスキーマ確認

1.　スキーマを確認します

aws quicksight describe-data-set \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --data-set-id monthly-sales-summary \
    --region ap-northeast-1
---

{
    "Status": 200,
    "DataSet": {
        "DataSetId": "monthly-sales-summary",
        "Name": "Monthly Sales Summary",
        "PhysicalTableMap": {
            "salesTable": {
                "RelationalTable": {
                    "DataSourceArn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:datasource/redshift-dev",
                    "Schema": "dm",
                    "Name": "monthly_sales_summary",
                    "InputColumns": [
                        {"Name": "sales_month", "Type": "INTEGER"},
                        {"Name": "category", "Type": "STRING"},
                        {"Name": "region", "Type": "STRING"},
                        {"Name": "quantity", "Type": "INTEGER"},
                        {"Name": "revenue", "Type": "DECIMAL", "SubType": "FIXED"}
                    ]
                }
            }
        },
        "ImportMode": "SPICE",
        "ConsumedSpiceCapacityInBytes": 1940
    }
}

最小構成でダッシュボードを作成する

既存データセット monthly-sales-summary を参照して空シートのダッシュボードを作ります。

ダッシュボード作成

1.　APIでダッシュボードを作成します。CREATION_IN_PROGRESSになりました

aws quicksight create-dashboard \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --name "API Test Dashboard" \
    --definition '{
        "DataSetIdentifierDeclarations": [
            {
                "Identifier": "my_dataset",
                "DataSetArn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dataset/monthly-sales-summary"
            }
        ],
        "Sheets": [
            {
                "SheetId": "sheet-1",
                "Name": "Sheet 1",
                "Visuals": [],
                "Layouts": [
                    {
                        "Configuration": {
                            "GridLayout": {
                                "Elements": []
                            }
                        }
                    }
                ]
            }
        ]
    }' \
    --region ap-northeast-1

---
{
    "Status": 202,
    "Arn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dashboard/api-test-dashboard-001",
    "VersionArn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dashboard/api-test-dashboard-001/version/1",
    "DashboardId": "api-test-dashboard-001",
    "CreationStatus": "CREATION_IN_PROGRESS"
}

2.　ステータスを確認します。CREATION_SUCCESSFULになっていました

aws quicksight describe-dashboard \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --region ap-northeast-1
---
{
    "Status": 200,
    "Dashboard": {
        "DashboardId": "api-test-dashboard-001",
        "Name": "API Test Dashboard",
        "Version": {
            "VersionNumber": 1,
            "Status": "CREATION_SUCCESSFUL",
            "Errors": [],
            "DataSetArns": [
                "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dataset/monthly-sales-summary"
            ],
            "Sheets": [
                {"SheetId": "sheet-1", "Name": "Sheet 1"}
            ]
        }
    }
}

3.　コンソール表示のため、権限を付与します

aws quicksight update-dashboard-permissions \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --grant-permissions '[{
        "Principal": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:user/default/${QS_USER_NAME}",
        "Actions": [
            "quicksight:DescribeDashboard",
            "quicksight:ListDashboardVersions",
            "quicksight:UpdateDashboardPermissions",
            "quicksight:QueryDashboard",
            "quicksight:UpdateDashboard",
            "quicksight:DeleteDashboard",
            "quicksight:UpdateDashboardPublishedVersion",
            "quicksight:DescribeDashboardPermissions"
        ]
    }]' \
    --region ap-northeast-1
---
{
    "Status": 200,
    "DashboardId": "api-test-dashboard-001",
    "Permissions": [
        {
            "Principal": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:user/default/${QS_USER_NAME}",
            "Actions": ["quicksight:DescribeDashboard", "quicksight:QueryDashboard", "..."]
        }
    ]
}

GUIで確認する

1.　AWSにサインイン後QSで確認してみます。対象のダッシュボードが表示されています
image.png

2.　現時点では何も見えません
image.png

ダッシュボードを更新する

更新前の確認

1.　更新前の状態を確認します

aws quicksight describe-dashboard-definition \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --region ap-northeast-1
---
{
    "Definition": {
        "Sheets": [{
            "SheetId": "sheet-1",
            "Name": "Sheet 1",
            "Visuals": [],
            "Layouts": [{"Configuration": {"GridLayout": {"Elements": []}}}],
            "ContentType": "INTERACTIVE"
        }]
    }
}

ダッシュボード更新

1.　ダッシュボードを更新します

aws quicksight update-dashboard \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --name "API Test Dashboard" \
    --definition '{
        "DataSetIdentifierDeclarations": [{
            "Identifier": "my_dataset",
            "DataSetArn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dataset/monthly-sales-summary"
        }],
        "Sheets": [{
            "SheetId": "sheet-1",
            "Name": "Sheet 1",
            "Visuals": [{
                "TableVisual": {
                    "VisualId": "table-visual-1",
                    "Title": {
                        "Visibility": "VISIBLE",
                        "FormatText": {"PlainText": "Monthly Sales Summary"}
                    },
                    "ChartConfiguration": {
                        "FieldWells": {
                            "TableUnaggregatedFieldWells": {
                                "Values": [
                                    {"FieldId": "sales_month", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "sales_month"}},
                                    {"FieldId": "category", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "category"}},
                                    {"FieldId": "region", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "region"}},
                                    {"FieldId": "quantity", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "quantity"}},
                                    {"FieldId": "revenue", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "revenue"}}
                                ]
                            }
                        }
                    }
                }
            }],
            "Layouts": [{
                "Configuration": {
                    "GridLayout": {
                        "Elements": [{
                            "ElementId": "table-visual-1",
                            "ElementType": "VISUAL",
                            "ColumnSpan": 36,
                            "RowSpan": 12
                        }]
                    }
                }
            }],
            "ContentType": "INTERACTIVE"
        }]
    }' \
    --region ap-northeast-1

---
{
    "Status": 202,
    "DashboardId": "api-test-dashboard-001",
    "VersionArn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dashboard/api-test-dashboard-001/version/2",
    "CreationStatus": "CREATION_IN_PROGRESS"
}

バージョン公開

update-dashboard は新バージョンを作成するだけで、自動では公開されません。

1.　公開バージョンを切り替えます。

aws quicksight update-dashboard-published-version \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --version-number 2 \
    --region ap-northeast-1

----
{
    "Status": 200,
    "DashboardId": "api-test-dashboard-001"
}

更新後の確認

1.　更新後の状態を確認します

aws quicksight describe-dashboard-definition \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --region ap-northeast-1
----
{
    "Definition": {
        "Sheets": [{
            "SheetId": "sheet-1",
            "Name": "Sheet 1",
            "Visuals": [{
                "TableVisual": {
                    "VisualId": "table-visual-1",
                    "Title": {"Visibility": "VISIBLE", "FormatText": {"PlainText": "Monthly Sales Summary"}},
                    "ChartConfiguration": {
                        "FieldWells": {
                            "TableUnaggregatedFieldWells": {
                                "Values": [
                                    {"FieldId": "sales_month", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "sales_month"}},
                                    {"FieldId": "category", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "category"}},
                                    {"FieldId": "region", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "region"}},
                                    {"FieldId": "quantity", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "quantity"}},
                                    {"FieldId": "revenue", "Column": {"DataSetIdentifier": "my_dataset", "ColumnName": "revenue"}}
                                ]
                            }
                        }
                    }
                }
            }],
            "Layouts": [{
                "Configuration": {
                    "GridLayout": {
                        "Elements": [{"ElementId": "table-visual-1", "ElementType": "VISUAL", "ColumnSpan": 36, "RowSpan": 12}]
                    }
                }
            }]
        }]
    }
}

GUIで確認する

1.　APIで更新後に実際にAWS上で確認します。見えました

image.png

考察

  • Definition APIを使えば、GUIを一切操作せずにダッシュボードの作成・更新が可能だった
  • update-dashboard → update-dashboard-published-version の2ステップが必要な点は、逆に言えば公開前にJSON上でレビューできるメリットがある
  • Definition JSONの構造さえ把握すれば、生成AIに「テーブルビジュアルを追加して」と依頼して返ってきたJSONをそのまま update-dashboard に渡すワークフローが成立しそうだと感じた
  • CLIで作成したリソースに権限が自動付与されない点は、初見だとハマりやすい。create-dashboard 時に --permissions を指定するのがベストプラクティス

参考

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?