[アップデート] Amazon QuickSight で ダッシュボードのスナップショット API が使えるようになっていたようなので試してみた

[アップデート] Amazon QuickSight で ダッシュボードのスナップショット API が使えるようになっていたようなので試してみた

#Amazon QuickSight
#AWS
いわさ

いわさ

facebook logohatena logotwitter logo
Clock Icon2023.07.30

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

いわさです。

数日前に Amazon QuickSight に次の新しい API が追加されました。

しかし、その後アップデートアナウンスもなく、公式ドキュメントの変更も見当たらずの状態でした。

アップデートアナウンス見落としてました。ありました。

API ドキュメントから雰囲気を読み取った限りでは、作成済みのダッシュボードを指定することで PDF あるいは CSV 形式でダッシュボードの「スナップショット」を作成出来るようです。

少し前に QuickSight でダッシュボードを初めとするアセットのエクスポートとインポート機能がサポートされましたが、これとは別でしょうか。

あるいは、ダッシュボードには既に PDF エクスポート機能が存在していますが、こちらとは別でしょうか。

本日はこの API を実際に使ってみて、ここでいうスナップショットが何を指していて、そしてどういう用途で使えそうなのかを確認してみました。

Paginated Reports（分割されたレポート）アドオンが必須

まず、次のような適当なダッシュボードで使ってみました。

start-dashboard-snapshot-jobコマンドのパラメータで上記ダッシュボードを指定します。
次のパラメータでは対象ダッシュボードの特定シートを PDF 形式で S3 バケットへ出力する構成となっています。

{
    "AwsAccountId": "123456789012",
    "DashboardId": "b7069228-45d0-4b49-910f-352eb2c8b0a8",
    "SnapshotJobId": "hogesnapshot1",
    "UserConfiguration": {
        "AnonymousUsers": [
            {
                "RowLevelPermissionTags": [
                    {
                        "Key": "hoge-key",
                        "Value": "hoge-value"
                    }
                ]
            }
        ]
    },
    "SnapshotConfiguration": {
        "FileGroups": [
            {
                "Files": [
                    {
                        "SheetSelections": [
                            {
                                "SheetId": "b7069228-45d0-4b49-910f-352eb2c8b0a8_406b8827-9459-4a48-9ab7-c30b2f1d82f1",
                                "SelectionScope": "ALL_VISUALS"
                            }
                        ],
                        "FormatType": "PDF"
                    }
                ]
            }
        ],
        "DestinationConfiguration": {
            "S3Destinations": [
                {
                    "BucketConfiguration": {
                        "BucketName": "hoge0730quicksight",
                        "BucketPrefix": "hoge1",
                        "BucketRegion": "ap-northeast-1"
                    }
                }
            ]
        }
    }
}

シートの指定は必須で、形式としては PDF と CSV が指定可能です。CSV も今回試していますので後ほど紹介します。
また、出力先（DestinationConfiguration）は、本日時点では S3 バケットのみ指定可能です。
UserConfiguration はパブリックアクセスを有効化した際に匿名ユーザーの RLS を機能させるためにセッションタグを使う必要があるのですが、作成するスナップショット向けに設定することが出来ます。設定することが出来るというか必須パラメータとなっています。
ここではタグは不要なのですが、適当なダミー値を指定しました。

上記のパラメータを実行したところ次のようなエラーメッセージが表示されました。

% aws quicksight start-dashboard-snapshot-job --cli-input-json file://hoge.json

An error occurred (UnsupportedPricingPlanException) when calling the StartDashboardSnapshotJob operation: This API action is supported only when the account has an active paginated reports add-on plan.

This API action is supported only when the account has an active paginated reports add-on plan.

な、なるほど...！この API どうやら Paginated Reports が前提みたいですね。
Paginated Reports というのは、re:Invent 2022 で登場した QuickSight のオプション機能です。

次の記事では実際に試していて、通常の QuickSight から見るとちょっと料金がお高く、最低 500 USD/月から必要なオプション機能というのは有名です。

では、有効化しましょう。

これ、今回初めて有効化したのですが、私の記憶が間違って無ければ確認メッセージなしで有効化されましたね。
RDS の一時停止時みたいに、少ししつこいくらい確認メッセージ出してほしいかもしれないですね。

スナップショットは特定時点・条件で生成されたコンテンツ

これで前提条件のひとつめである Paginated Reports は有効化されましたので、再びスナップショットとやらを作成してみましょう。

PDF 形式（ページ分割されたレポートシートが前提）

まずは、PDF からです。
先程と同じ条件で試したところ、今度は別のエラーが発生しました。

% aws quicksight start-dashboard-snapshot-job --cli-input-json file://hoge.json --profile hogeadmin

An error occurred (InvalidParameterValueException) when calling the StartDashboardSnapshotJob operation: PDF only supports generating Sheets that are PAGINATED

なるほど。有効化するだけじゃなくて対象シートが Paginated Reports モードで作成されてる必要あるとのこと。
これはどういうことかというと、まず QuickSight の分析内にはシートの概念があります。
そして、シートを新規作成するときには次のようにインタラクティブシートかページ分割されたレポートか、どちらかを選択するようになっています。

start-dashboard-snapshot-jobコマンドのパラメータ内で指定されたシートはインタラクティブシートで作成されたものでした。
PDF 形式でスナップショットを生成する場合はページ分割されたレポートとして作成されたシートである必要がありますので次のように新規作成しました。

後述しますが、CSV 形式の場合はインタラクティブシートでも大丈夫です。

ダッシュボード化しましょう。
冒頭の Pagenated Reports 紹介記事でも触れられていますが、レポートは別途スケジュール設定や出力操作が前提になっており、コンソール上はこのように表示されています。

start-dashboard-snapshot-job

ここで、次のパラメータファイルを使って PDF 形式でスナップショット作成ジョブを開始します。
注意点としては、PDF 形式の場合はSelectionScopeにALL_VISUALSを指定する必要があります。

{
    "AwsAccountId": "123456789012",
    "DashboardId": "54a1b9db-2025-436d-a05c-cee7510aaf89",
    "SnapshotJobId": "hogesnapshot1",
    "UserConfiguration": {
        "AnonymousUsers": [
            {
                "RowLevelPermissionTags": [
                    {
                        "Key": "hoge-key",
                        "Value": "hoge-value"
                    }
                ]
            }
        ]
    },
    "SnapshotConfiguration": {
        "FileGroups": [
            {
                "Files": [
                    {
                        "SheetSelections": [
                            {
                                "SheetId": "54a1b9db-2025-436d-a05c-cee7510aaf89_53346441-84f3-4c06-b9f2-42df99041947",
                                "SelectionScope": "ALL_VISUALS"
                            }
                        ],
                        "FormatType": "PDF"
                    }
                ]
            }
        ],
        "DestinationConfiguration": {
            "S3Destinations": [
                {
                    "BucketConfiguration": {
                        "BucketName": "hoge0730snapshot1",
                        "BucketPrefix": "hoge1",
                        "BucketRegion": "ap-northeast-1"
                    }
                }
            ]
        }
    }
}

実行してみると、ジョブの開始に成功したようです。

% aws quicksight start-dashboard-snapshot-job --cli-input-json file://hoge.json --profile hogeadmin
{
    "Status": 200,
    "Arn": "arn:aws:quicksight:ap-northeast-1:123456789012:dashboard/54a1b9db-2025-436d-a05c-cee7510aaf89/snapshot-job/hogesnapshot1",
    "SnapshotJobId": "hogesnapshot1",
    "RequestId": "67fafdaf-8114-467e-b9eb-4dc50e2d829b"
}

describe-dashboard-snapshot-job

開始したジョブは数秒で完了するものではないのでジョブの状況をウォッチする必要があります。
describe-dashboard-snapshot-jobを使うことでジョブステータスなどを確認することが可能です。

                                                                   
{
    "AwsAccountId": "123456789012",
    "DashboardId": "54a1b9db-2025-436d-a05c-cee7510aaf89",
    "SnapshotJobId": "hogesnapshot1"
}

% aws quicksight describe-dashboard-snapshot-job --cli-input-json file://hoge2.json --profile hogeadmin
{
    "AwsAccountId": "123456789012",
    "DashboardId": "54a1b9db-2025-436d-a05c-cee7510aaf89",
    "SnapshotJobId": "hogesnapshot1",
    "UserConfiguration": {
        "AnonymousUsers": [
            {
                "RowLevelPermissionTagKeys": [
                    "hoge-key"
                ]
            }
        ]
    },
    "SnapshotConfiguration": {
        "FileGroups": [
            {
                "Files": [
                    {
                        "SheetSelections": [
                            {
                                "SheetId": "54a1b9db-2025-436d-a05c-cee7510aaf89_53346441-84f3-4c06-b9f2-42df99041947",
                                "SelectionScope": "ALL_VISUALS"
                            }
                        ],
                        "FormatType": "PDF"
                    }
                ]
            }
        ],
        "DestinationConfiguration": {
            "S3Destinations": [
                {
                    "BucketConfiguration": {
                        "BucketName": "hoge0730snapshot1",
                        "BucketPrefix": "hoge1",
                        "BucketRegion": "ap-northeast-1"
                    }
                }
            ]
        },
        "Parameters": {
            "StringParameters": [],
            "IntegerParameters": [],
            "DecimalParameters": [],
            "DateTimeParameters": []
        }
    },
    "Arn": "arn:aws:quicksight:ap-northeast-1:123456789012:dashboard/54a1b9db-2025-436d-a05c-cee7510aaf89/snapshot-job/hogesnapshot1",
    "JobStatus": "RUNNING",
    "CreatedTime": "2023-07-30T05:42:32.850000+09:00",
    "LastUpdatedTime": "2023-07-30T05:42:32.850000+09:00",
    "RequestId": "b5ba8b99-9589-4a20-9576-af78759059b4",
    "Status": 200
}

JobStatusがRUNNINGですね。試した限りですが 1 つのジョブは数秒ではなく数十秒〜数分かけて実行されるようです。

describe-dashboard-snapshot-job-result

しばらくするとジョブステータスがCOMPLETEDになります。（あるいはエラーステータス） そうするとdescribe-dashboard-snapshot-job-resultコマンドでジョブの結果と S3 へ出力されたファイルの URL を取得することが出来ます。
実行結果はこちらです。

% aws quicksight describe-dashboard-snapshot-job-result --cli-input-json file://hoge2.json --profile hogeadmin
{
    "Status": 200,
    "Arn": "arn:aws:quicksight:ap-northeast-1:123456789012:dashboard/54a1b9db-2025-436d-a05c-cee7510aaf89/snapshot-job/hogesnapshot1",
    "JobStatus": "COMPLETED",
    "CreatedTime": "2023-07-30T05:42:32.850000+09:00",
    "LastUpdatedTime": "2023-07-30T05:45:56.098000+09:00",
    "Result": {
        "AnonymousUsers": [
            {
                "FileGroups": [
                    {
                        "Files": [
                            {
                                "SheetSelections": [
                                    {
                                        "SheetId": "54a1b9db-2025-436d-a05c-cee7510aaf89_53346441-84f3-4c06-b9f2-42df99041947",
                                        "SelectionScope": "ALL_VISUALS"
                                    }
                                ],
                                "FormatType": "PDF"
                            }
                        ],
                        "S3Results": [
                            {
                                "S3DestinationConfiguration": {
                                    "BucketConfiguration": {
                                        "BucketName": "hoge0730snapshot1",
                                        "BucketPrefix": "hoge1",
                                        "BucketRegion": "ap-northeast-1"
                                    }
                                },
                                "S3Uri": "s3://hoge0730snapshot1/hoge1/report1_2023-07-29T20_43_14_zpY2uwRrs3_2023_07_29_20_45_37_GMT.pdf"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "RequestId": "8b175a5c-3097-43c9-9835-030e74b0a8a6"
}

S3Uriのパスを確認してみるとスナップショットと呼ばれるコンテンツが出力されています。
中身を確認してみましょう。

次のような PDF レポートが出力されていますね。

要はスナップショットというのはダッシュボードコンテンツをダウンロード可能な形式で出力されたものを指しているようです。
バックアップデータとかそういうものではなくて、通常出力されるレポートコンテンツですねこれは。

CSV 形式（インタラクティブシートのビジュアルも指定可能）

続いて CSV 形式も使ってみましょう。
CSV 形式の場合は、パラメータにてシートに加えてビジュアルの指定が必要です。
そして指定可能なビジュアルはテーブルとピボットテーブルのみとなっています。

次のようにテーブルビジュアルを配置してビジュアルのデベロッパー向け ID を取得します。

こちらを使ってジョブ開始用のパラメータを作成します。

                                                                                    
{
    "AwsAccountId": "123456789012",
    "DashboardId": "54a1b9db-2025-436d-a05c-cee7510aaf89",
    "SnapshotJobId": "hogesnapshot2",
    "UserConfiguration": {
        "AnonymousUsers": [
            {
                "RowLevelPermissionTags": [
                    {
                        "Key": "hoge-key",
                        "Value": "hoge-value"
                    }
                ]
            }
        ]
    },
    "SnapshotConfiguration": {
        "FileGroups": [
            {
                "Files": [
                    {
                        "SheetSelections": [
                            {
                                "SheetId": "54a1b9db-2025-436d-a05c-cee7510aaf89_bb2cb3a0-149f-49a4-b1f2-2a53d425ed34",
                                "SelectionScope": "SELECTED_VISUALS",
                                "VisualIds": [
                                    "54a1b9db-2025-436d-a05c-cee7510aaf89_8cfad577-c068-40b8-bbd2-2398a0ecb4a4"
                                ]
                            }
                        ],
                        "FormatType": "CSV"
                    }
                ]
            }
        ],
        "DestinationConfiguration": {
            "S3Destinations": [
                {
                    "BucketConfiguration": {
                        "BucketName": "hoge0730snapshot1",
                        "BucketPrefix": "hoge1",
                        "BucketRegion": "ap-northeast-1"
                    }
                }
            ]
        }
    }
}

なお、上記で成功しましたが、SelectionScopeにALL_VISUALSを指定したところ次のようなエラーとなりましたので紹介しておきます。

% aws quicksight start-dashboard-snapshot-job --cli-input-json file://hoge.json --profile hogeadmin           

An error occurred (InvalidParameterValueException) when calling the StartDashboardSnapshotJob operation: CSV only supports generating SELECTED_VISUALS for SheetSelections.SelectionScope. Only 1 visual per CSV

このあとのジョブのステータスを確認して、結果を確認する流れは同じなので割愛しますが、最終的には次のように指定した S3 バケットへ CSV ファイルが出力されました。

CSV ファイルをダウンロードして内容を確認してみると、次のように対象のテーブルビジュアルに表示された内容（おそらく CSV エクスポート相当）が表示されていますね。
これはもしかしたら将来的に Excel へのエクスポートがサポートされる可能性もあるかもしれないですね。

"name","col1","col2","col3"
"user1","aaa",10,20
"user2","aaa",11,20
"user4","aaa",15,15
"user3","bbb",12,30
"user5","bbb",14,16

ちなみに、ページ分割レポートの場合は、ビジュアル選択という概念がないのかなと最初思ったのですが、describe-dashboard-definitionコマンドでダッシュボードの定義を確認してみると、インタラクティブシートと同様にビジュアル ID が割り振られており、そちらを指定することで同じように出力されることを確認しました。

単一のジョブで複数の出力を指定する

条件がいくつかあるのですが、単一のジョブで複数ファイルを出力するような指定方法が可能です。
条件はstart-dashboard-snapshot-jobのリファレンスの記述されていて、「API 呼び出しごとに、最大 1 つのページ分割された PDF と最大 5 つの CSV をリクエストできる」とのことです。

複数ファイルの指定方法は次のようにFileGroupsにリスト指定することで出力が出来ました。

{
    "AwsAccountId": "123456789012",
    "DashboardId": "54a1b9db-2025-436d-a05c-cee7510aaf89",
    "SnapshotJobId": "hogesnapshot5",
    "UserConfiguration": {
        "AnonymousUsers": [
            {
                "RowLevelPermissionTags": [
                    {
                        "Key": "hoge-key",
                        "Value": "hoge-value"
                    }
                ]
            }
        ]
    },
    "SnapshotConfiguration": {
        "FileGroups": [
            {
                "Files": [
                    {
                        "SheetSelections": [
                            {
                                "SheetId": "54a1b9db-2025-436d-a05c-cee7510aaf89_53346441-84f3-4c06-b9f2-42df99041947",
                                "SelectionScope": "ALL_VISUALS"
                            }
                        ],
                        "FormatType": "PDF"
                    }
                ]
            },
            {
                "Files": [
                    {
                        "SheetSelections": [
                            {
                                "SheetId": "54a1b9db-2025-436d-a05c-cee7510aaf89_bb2cb3a0-149f-49a4-b1f2-2a53d425ed34",
                                "SelectionScope": "SELECTED_VISUALS",
                                "VisualIds": [
                                    "54a1b9db-2025-436d-a05c-cee7510aaf89_8cfad577-c068-40b8-bbd2-2398a0ecb4a4"
                                ]
                            }
                        ],
                        "FormatType": "CSV"
                    }
                ]
            }
        ],
        "DestinationConfiguration": {
            "S3Destinations": [
                {
                    "BucketConfiguration": {
                        "BucketName": "hoge0730snapshot1",
                        "BucketPrefix": "hoge5",
                        "BucketRegion": "ap-northeast-1"
                    }
                }
            ]
        }
    }
}

PDF と CSV ファイルが同時に出力されていることが確認出来ますね。

ちなみにFilesやSheetSelectionsはリストではあるのですが、試しに複数指定して確認してみたところ次のようなエラーとなりました。

% aws quicksight start-dashboard-snapshot-job --cli-input-json file://hoge.json --profile hogeadmin

An error occurred (ValidationException) when calling the StartDashboardSnapshotJob operation: 1 validation error detected: Value '[SnapshotFile(sheetSelections=[SnapshotFileSheetSelection(sheetId=54a1b9db-2025-436d-a05c-cee7510aaf89_53346441-84f3-4c06-b9f2-42df99041947, selectionScope=ALL_VISUALS, visualIds=null)], formatType=PDF), SnapshotFile(sheetSelections=[SnapshotFileSheetSelection(sheetId=54a1b9db-2025-436d-a05c-cee7510aaf89_03fbefb8-f5a8-42df-be34-6067d2ba45ad, selectionScope=ALL_VISUALS, visualIds=null)], formatType=PDF)]' at 'snapshotConfiguration.fileGroups.1.member.files' failed to satisfy constraint: Member must have length less than or equal to 1

CSV 形式でも Paginated Reports アドオンは必須

CSV 形式であればインタラクティブシートが指定出来るので、CSV 形式のみの利用であれば Paginated Reports アドオン不要なのでは？と思い、アドオンをサブスクライブしていないアカウントで試してみたところ、次のようにエラーが発生しました。

% aws quicksight start-dashboard-snapshot-job --cli-input-json file://hoge.json

An error occurred (UnsupportedPricingPlanException) when calling the StartDashboardSnapshotJob operation: This API action is supported only when the account has an active paginated reports add-on plan.

どうやら CSV 形式でも Paginated Reports アドオンは必須のようですね。

さいごに

本日は Amazon QuickSight で Dashboard SnapShot API が使えるようになってたようなので試してみました。

まず、大前提として Paginated Reports アドオンが必須となります。
また、ここでいうスナップショットは何かの復元用途に使えるものではなくて、特定時点・条件で出力したレポートコンテンツです。

おそらく、用途としては標準のスケジュール機能以外で QuickSight 外から API 経由でアドホックレポートを作成したり、あるいは外部アプリケーションの帳票出力や CSV 出力処理の代用として使うのかなという感じです。
ただ、生成までちょっと時間が（今回検証した簡単なもので 2 ~ 3 分くらい）かかるので、後者に関しては使用感確かめてみたほうが良いでしょう。
生成に長時間が許容出来るような大規模なレポート出力機能としてであれば採用出来るかもしれない。

Share this article

facebook logohatena logotwitter logo

関連記事

[アップデート] Amazon QuickSight のデータセットでユニークキーが設定出来るようになったので挙動を検証してみた

[アップデート] Amazon QuickSight のデータセットでユニークキーが設定出来るようになったので挙動を検証してみた

User avatar
いわさ
2024.12.21
Amazon QuickSight 2024年 アップデートまとめ

Amazon QuickSight 2024年 アップデートまとめ

User avatar
いわさ
2024.12.16
[レポート] Build a vehicle insights assistant with AWS IoT and Amazon Q #AUT304-R1

[レポート] Build a vehicle insights assistant with AWS IoT and Amazon Q #AUT304-R1

User avatar
新澤忠士
2024.12.09
[レポート] Q in QuickSight を使って生成 AI でダッシュボードをゼロから生成するワークショップ「Empower executives: Self-service dashboards with Generative BI」 #NTA404 #AWSreInvent

[レポート] Q in QuickSight を使って生成 AI でダッシュボードをゼロから生成するワークショップ「Empower executives: Self-service dashboards with Generative BI」 #NTA404 #AWSreInvent

User avatar
emi
2024.12.07
Classmethod's white logo
Facebook's logo
X's logo
YouTube's logo

© Classmethod, Inc. All rights reserved.