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でダッシュボードの設定を取得・変更してみた

0
Posted at

背景・目的

前回までの記事では、Definition APIでダッシュボードを作成・更新し、Asset Bundle APIで環境間の移行を試しました。

本記事では、QuickSight APIを使ってダッシュボードの設定を確認することを試します。

ダッシュボードのテーマ・ディスプレイ設定・ヘッダー・公開設定など、通常はGUIで1つずつ画面を開いて確認しますが、帳票数が多いと非常に手間がかかります。

本記事では、これらの設定値をAPIで取得できるか検証します。

  1. describe-theme でテーマ設定を取得
  2. describe-dashboard-definition でディスプレイ設定・ヘッダー・セル・カスタム色を取得
  3. describe-dashboard-definition で公開設定を取得

まとめ

下記に特徴を整理します。

項目 内容
GUIで確認する設定項目 テーマ、ヘッダー・セル・カスタム色、公開設定の3種類
カスタムテーマとは 組み込みテーマ（CLASSIC等）をベースに、カラーパレット・フォント等を独自定義したもの
APIで設定を確認するアプローチ describe-theme、describe-dashboard-definition で設定値をJSON取得。変更も1コマンドで完了
テーマの取得・変更 describe-theme / create-theme / update-theme
ヘッダー・セル・カスタム色の取得・変更 describe-dashboard-definition / update-dashboard
公開設定の取得・変更 describe-dashboard-definition / update-dashboard + update-dashboard-published-version

概要

GUIで確認する設定項目

QuickSightのダッシュボードには、以下のような設定項目があります。

  1. テーマ — カラーパレット、フォント等の見た目の統一設定
  2. ヘッダー・セル・カスタム色 — テーブルビジュアルのヘッダー背景色、セルのスタイル
  3. ダッシュボードの公開設定 — フィルタリング・PDF出力・ドリルダウン等のオプション

これらはGUIでプロパティパネルや公開ダイアログを開いて確認しますが、ダッシュボード数が多いと手間がかかります。

カスタムテーマとは

QuickSightには組み込みテーマ（CLASSIC、MIDNIGHT、SEASIDE等）が用意されていますが、独自のカラーパレットやフォントを定義したい場合はカスタムテーマを作成します。

カスタムテーマで設定できる項目：

  • DataColorPalette — グラフの色（棒グラフ、折れ線グラフ等に使われる色の配列）
  • UIColorPalette — UI要素の色（アクセントカラー、背景色、警告色等）
  • Sheet — タイルのボーダー、マージン設定
  • Typography — フォントファミリー、フォントサイズ

テーマはダッシュボードの見た目を統一するための仕組みで、1つのテーマを複数のダッシュボードに適用できます。

APIで設定を確認するアプローチ

GUIで1つずつ画面を開く代わりに、APIで設定値を取得・変更・確認します。

describe-theme                → テーマ設定（カラーパレット、フォント）
describe-dashboard-definition → ビジュアル設定（ヘッダー、セル、カスタム色）+ 公開設定

APIで操作するメリット：

  • 帳票数が多くても一括処理可能（スクリプト化できる）
  • 設定の取得だけでなく変更もコマンド1つで完了する
  • 差分比較が容易（JSONのdiff）

使うAPIの全体像

API 用途
describe-theme テーマの設定（カラーパレット、Typography）取得
describe-dashboard-definition ダッシュボードの中身（ビジュアル設定・レイアウト）取得
describe-dashboard ダッシュボードのメタ情報（公開設定含む）取得
list-themes カスタムテーマの一覧取得

実践

前提

  • AWS CLIを使用
  • QuickSight Enterprise Editionを利用
  • リージョン: ap-northeast-1

観点1: テーマ

カスタムテーマ一覧取得

1.　カスタムテーマ一覧を取得します。Listはありませんでした。

aws quicksight list-themes \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --type CUSTOM \
    --region ap-northeast-1

---

{
    "ThemeSummaryList": [],
    "Status": 200,
    "RequestId": "bb3079e5-cecc-428b-bfce-17b5bcbbebe2"
}

カスタムテーマ作成

1.　カスタムテーマがなかったので作成します

aws quicksight create-theme \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --theme-id test-theme-001 \
    --name "Test Theme 001" \
    --base-theme-id CLASSIC \
    --configuration '{
        "DataColorPalette": {
            "Colors": ["#9FDEF1","#2A5D78","#F6AA54","#B9E52F","#E436BB","#6197E2","#863CFF","#30CB71"],
            "MinMaxGradient": ["#DEF5FF","#219FD7"],
            "EmptyFillColor": "#D8D8D8"
        },
        "UIColorPalette": {
            "PrimaryForeground": "#212121",
            "PrimaryBackground": "#FFFFFF",
            "Accent": "#219FD7",
            "AccentForeground": "#FFFFFF"
        },
        "Typography": {
            "FontFamilies": [{"FontFamily": "Amazon Ember"},{"FontFamily": "sans-serif"}]
        }
    }' \
    --permissions '[{
        "Principal": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:user/default/${QS_USER_NAME}",
        "Actions": [
            "quicksight:ListThemeVersions",
            "quicksight:UpdateThemeAlias",
            "quicksight:DescribeThemeAlias",
            "quicksight:UpdateThemePermissions",
            "quicksight:DeleteThemeAlias",
            "quicksight:DeleteTheme",
            "quicksight:ListThemeAliases",
            "quicksight:DescribeTheme",
            "quicksight:CreateThemeAlias",
            "quicksight:UpdateTheme",
            "quicksight:DescribeThemePermissions"
        ]
    }]' \
    --region ap-northeast-1

---
json
{
    "Status": 202,
    "Arn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:theme/test-theme-001",
    "VersionArn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:theme/test-theme-001/version/1",
    "ThemeId": "test-theme-001",
    "CreationStatus": "CREATION_IN_PROGRESS",
    "RequestId": "e7bba7c7-508f-469a-8874-911dbde7d56d"
}

カスタムテーマの設定を取得

1.　作成後に取得します。さきほど設定したConfigurationが取得できました

aws quicksight describe-theme \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --theme-id test-theme-001 \
    --region ap-northeast-1

----

{
    "Status": 200,
    "Theme": {
        "Arn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:theme/test-theme-001",
        "Name": "Test Theme 001",
        "ThemeId": "test-theme-001",
        "Version": {
            "VersionNumber": 1,
            "BaseThemeId": "CLASSIC",
            "CreatedTime": "2026-06-10T17:45:51.109000+09:00",
            "Configuration": {
                "DataColorPalette": {
                    "Colors": [
                        "#9FDEF1", "#2A5D78", "#F6AA54", "#B9E52F",
                        "#E436BB", "#6197E2", "#863CFF", "#30CB71"
                    ],
                    "MinMaxGradient": ["#DEF5FF", "#219FD7"],
                    "EmptyFillColor": "#D8D8D8"
                },
                "UIColorPalette": {
                    "PrimaryForeground": "#212121",
                    "PrimaryBackground": "#FFFFFF",
                    "Accent": "#219FD7",
                    "AccentForeground": "#FFFFFF"
                },
                "Typography": {
                    "FontFamilies": [
                        {"FontFamily": "Amazon Ember"},
                        {"FontFamily": "sans-serif"}
                    ]
                }
            },
            "Status": "CREATION_SUCCESSFUL"
        },
        "Type": "CUSTOM"
    }
}

カスタムテーマの設定を変更

1.　カスタムテーマの設定を変更します
- Accent色を #219FD7 → #FF5733 に変えます

aws quicksight update-theme \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --theme-id test-theme-001 \
    --base-theme-id CLASSIC \
    --configuration '{
        "DataColorPalette": {
            "Colors": ["#FF0000","#00FF00","#0000FF","#FFFF00","#FF00FF","#00FFFF","#FFA500","#800080"],
            "MinMaxGradient": ["#DEF5FF","#219FD7"],
            "EmptyFillColor": "#D8D8D8"
        },
        "UIColorPalette": {
            "PrimaryForeground": "#212121",
            "PrimaryBackground": "#FFFFFF",
            "Accent": "#FF5733",
            "AccentForeground": "#FFFFFF"
        },
        "Typography": {
            "FontFamilies": [{"FontFamily": "Amazon Ember"},{"FontFamily": "sans-serif"}]
        }
    }' \
    --region ap-northeast-1

---

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

2.　変更されたか確認します。 UIColorPalette>Accentが#FF5733になりました。

aws quicksight describe-theme \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --theme-id test-theme-001 \
    --region ap-northeast-1

---

{
    "Status": 200,
    "Theme": {
        "Name": "Test Theme 001",
        "ThemeId": "test-theme-001",
        "Version": {
            "VersionNumber": 2,
            "BaseThemeId": "CLASSIC",
            "Configuration": {
                "DataColorPalette": {
                    "Colors": ["#FF0000","#00FF00","#0000FF","#FFFF00","#FF00FF","#00FFFF","#FFA500","#800080"],
                    "MinMaxGradient": ["#DEF5FF","#219FD7"],
                    "EmptyFillColor": "#D8D8D8"
                },
                "UIColorPalette": {
                    "PrimaryForeground": "#212121",
                    "PrimaryBackground": "#FFFFFF",
                    "Accent": "#FF5733",
                    "AccentForeground": "#FFFFFF"
                },
                "Typography": {
                    "FontFamilies": [
                        {"FontFamily": "Amazon Ember"},
                        {"FontFamily": "sans-serif"}
                    ]
                }
            },
            "Status": "CREATION_SUCCESSFUL"
        },
        "Type": "CUSTOM"
    }
}

観点2: ヘッダー・セル・カスタム色

ダッシュボードDefinition取得

1.　ダッシュボードのDefinitionを取得します。DashboardPublishOptionsも取得できました

aws quicksight describe-dashboard-definition \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --region ap-northeast-1
---

{
    "Status": 200,
    "DashboardId": "api-test-dashboard-001",
    "Name": "API Test Dashboard",
    "ResourceStatus": "CREATION_SUCCESSFUL",
    "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"
                                }
                            },
                            "Subtitle": {
                                "Visibility": "VISIBLE"
                            },
                            "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"}}
                                        ]
                                    }
                                },
                                "SortConfiguration": {}
                            },
                            "Actions": []
                        }
                    }
                ],
                "Layouts": [
                    {
                        "Configuration": {
                            "GridLayout": {
                                "Elements": [
                                    {"ElementId": "table-visual-1", "ElementType": "VISUAL", "ColumnSpan": 36, "RowSpan": 12}
                                ]
                            }
                        }
                    }
                ],
                "ContentType": "INTERACTIVE"
            }
        ]
    },
    "DashboardPublishOptions": {
        "AdHocFilteringOption": {"AvailabilityStatus": "ENABLED"},
        "ExportToCSVOption": {"AvailabilityStatus": "ENABLED"},
        "SheetControlsOption": {"VisibilityState": "COLLAPSED"},
        "SheetLayoutElementMaximizationOption": {"AvailabilityStatus": "ENABLED"},
        "VisualMenuOption": {"AvailabilityStatus": "ENABLED"},
        "VisualAxisSortOption": {"AvailabilityStatus": "ENABLED"},
        "ExportWithHiddenFieldsOption": {"AvailabilityStatus": "DISABLED"},
        "DataPointDrillUpDownOption": {"AvailabilityStatus": "ENABLED"},
        "DataPointMenuLabelOption": {"AvailabilityStatus": "ENABLED"},
        "DataPointTooltipOption": {"AvailabilityStatus": "ENABLED"},
        "DataQAEnabledOption": {"AvailabilityStatus": "DISABLED"},
        "ExecutiveSummaryOption": {"AvailabilityStatus": "ENABLED"},
        "DataStoriesSharingOption": {"AvailabilityStatus": "ENABLED"}
    }
}

update-dashboard でヘッダー色（例: #2D6DB1）やセルのスタイル設定をDefinitionに追加する

1.　TableOptionsを追加しました

- **HeaderStyle**: 背景色 #2D6DB1、文字色 白、フォント14px、高さ40
- **CellStyle**: 背景色 #F9F9F9、文字色 #333333、フォント12px、高さ32

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"
                                }
                            },
                            "Subtitle": {
                                "Visibility": "VISIBLE"
                            },
                            "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"}}
                                        ]
                                    }
                                },
                                "SortConfiguration": {},
                                "TableOptions": {
                                    "HeaderStyle": {
                                        "BackgroundColor": "#2D6DB1",
                                        "FontConfiguration": {
                                            "FontColor": "#FFFFFF",
                                            "FontSize": {"Absolute": "14px"}
                                        },
                                        "Height": 40
                                    },
                                    "CellStyle": {
                                        "BackgroundColor": "#F9F9F9",
                                        "FontConfiguration": {
                                            "FontColor": "#333333",
                                            "FontSize": {"Absolute": "12px"}
                                        },
                                        "Height": 32
                                    }
                                }
                            },
                            "Actions": []
                        }
                    }
                ],
                "Layouts": [
                    {
                        "Configuration": {
                            "GridLayout": {
                                "Elements": [
                                    {"ElementId": "table-visual-1", "ElementType": "VISUAL", "ColumnSpan": 36, "RowSpan": 12}
                                ]
                            }
                        }
                    }
                ],
                "ContentType": "INTERACTIVE"
            }
        ]
    }' \
    --region ap-northeast-1

---

{
    "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/3",
    "DashboardId": "api-test-dashboard-001",
    "CreationStatus": "CREATION_IN_PROGRESS",
    "Status": 202
}

公開と確認

1.　公開により、コンソールで見たときにヘッダー色・セル設定が反映されたものを確認します

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

---

{
    "Status": 200,
    "DashboardId": "api-test-dashboard-001",
    "DashboardArn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dashboard/api-test-dashboard-001"
}
  1. ヘッダー色・セル設定追加後のDefinitionを取得します
aws quicksight describe-dashboard-definition \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --region ap-northeast-1

~~~~~省略


"TableOptions": {
    "HeaderStyle": {
        "FontConfiguration": {
            "FontSize": {"Absolute": "14px"},
            "FontColor": "#FFFFFF"
        },
        "BackgroundColor": "#2D6DB1",
        "Height": 40
    },
    "CellStyle": {
        "FontConfiguration": {
            "FontSize": {"Absolute": "12px"},
            "FontColor": "#333333"
        },
        "BackgroundColor": "#F9F9F9",
        "Height": 32
    },
    "RowAlternateColorOptions": {
        "Status": "DISABLED"
    }
}

3.　QSで見てみます
image.png

観点3: ダッシュボードの公開設定

公開設定の変更

  1. 変更します（AdHocFilteringOption を ENABLED → DISABLED に変更します）※これにより、ビジュアルを右クリックしたときの「フィルター」メニューが消えて、作成者が事前に設定したフィルター以外は使えなくなります
aws quicksight update-dashboard \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --name "API Test Dashboard" \
    --definition '{ ... (省略: 前回と同じDefinition) ... }' \
    --dashboard-publish-options '{
        "AdHocFilteringOption": {"AvailabilityStatus": "DISABLED"},
        "ExportToCSVOption": {"AvailabilityStatus": "ENABLED"},
        "SheetLayoutElementMaximizationOption": {"AvailabilityStatus": "ENABLED"},
        "VisualMenuOption": {"AvailabilityStatus": "ENABLED"},
        "VisualAxisSortOption": {"AvailabilityStatus": "ENABLED"},
        "DataPointDrillUpDownOption": {"AvailabilityStatus": "ENABLED"},
        "DataPointMenuLabelOption": {"AvailabilityStatus": "ENABLED"},
        "DataPointTooltipOption": {"AvailabilityStatus": "ENABLED"}
    }' \
    --region ap-northeast-1

---

{
    "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/4",
    "DashboardId": "api-test-dashboard-001",
    "CreationStatus": "CREATION_IN_PROGRESS",
    "Status": 202
}

公開

1.　公開します

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


---


{
    "Status": 200,
    "DashboardId": "api-test-dashboard-001",
    "DashboardArn": "arn:aws:quicksight:ap-northeast-1:${AWS_ACCOUNT_ID}:dashboard/api-test-dashboard-001"
}

確認

1.　確認します。AdHocFilteringOption が DISABLED に変わっていることを確認できました

aws quicksight describe-dashboard-definition \
    --aws-account-id ${AWS_ACCOUNT_ID} \
    --dashboard-id api-test-dashboard-001 \
    --region ap-northeast-1

---

{
    "AdHocFilteringOption": {
        "AvailabilityStatus": "DISABLED"
    },
    "ExportToCSVOption": {
        "AvailabilityStatus": "ENABLED"
    },
    "SheetLayoutElementMaximizationOption": {
        "AvailabilityStatus": "ENABLED"
    },
    "VisualMenuOption": {
        "AvailabilityStatus": "ENABLED"
    },
    "VisualAxisSortOption": {
        "AvailabilityStatus": "ENABLED"
    },
    "ExportWithHiddenFieldsOption": {
        "AvailabilityStatus": "DISABLED"
    },
    "DataPointDrillUpDownOption": {
        "AvailabilityStatus": "ENABLED"
    },
    "DataPointMenuLabelOption": {
        "AvailabilityStatus": "ENABLED"
    },
    "DataPointTooltipOption": {
        "AvailabilityStatus": "ENABLED"
    }
}

2.　コンソールでも確認します。右クリックからフィルターが消えました

image.png

考察

  • describe-theme と describe-dashboard-definition の2つのAPIで、テーマ・ヘッダー・セル・カスタム色・公開設定のすべてをJSON形式で取得できることを確認した
  • GUIで1画面ずつ開いてスクリーンショットを撮る作業と比較すると、帳票数が多い場合にAPIのほうが圧倒的に効率が良い
  • 変更もAPIで完結するため、「取得 → diff確認 → 変更 → 再取得で確認」という一連のフローをスクリプト化できそうだ
  • ただし update-dashboard は毎回Definition全体を渡す必要があるため、部分的な設定変更でもJSONの全量管理が前提になる
  • update-dashboard と update-dashboard-published-version の2ステップが必要な点は、前回のDefinition API検証と同様。公開を忘れるとコンソールに反映されない
  • テーマの設定はダッシュボードのDefinitionとは別管理（describe-theme）のため、テーマ適用状態の確認は2つのAPIを組み合わせる必要がある

参考

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?