QuicksightのAsset as Codeのエラー要因を探る #AWS

はじめに

本記事では2023年6月に公開されたAmazon QuickSightに関する以下リリースについて、
アセット移行をAPIで実施した際にNGとなるケースがあるかどうかを検証をしてみました。
ある程度Quicksightを触ったことのある方向けの記事となっています。

Amazon QuickSight が、アセットのデプロイを自動化および高速化する API をサポート
 Amazon QuickSight - Visualization Basics コードでダッシュボードを作成する

新しくリリースされたAPI機能について

APIにて、アセット定義の作成・移行・編集が可能になりました（Asset as Code）
ビジュアルの定義情報をjson形式のファイルで出力し、
それをもとに新しい分析やダッシュボードを作成することができます。
（jsonファイルの内容を一部書き換えて新しい分析・ダッシュボードを作成することも可能）

アセット移行について

QuickSightのアセットとは、
データセットや分析、ダッシュボードなどQuickSight上のオブジェクトリソースを指します。

分析、ダッシュボードは手動で複製することもできますが、
別の環境にコピーしたい場合などは手動複製では移行できないため、APIを使用する必要があります。

今回は、アセット移行をした際にどういった場合にエラーとなるのかを検証しました。

検証内容

今回は大きく２つの観点で検証を実施しました。
（1）エラー調査
　　　分析に特定の文字や設定が含まれている場合に問題なく移行ができるか
（2）書き換え調査
　　　出力した分析定義ファイルの内容を手動で書き換えて問題なく移行できるか

詳細は以下の通りです。
以前試行した際にエラーを確認した部分を中心に、確認項目を設定しています。

各項目について、以下に補足します。
※細かい内容ですので読み飛ばしても問題ありません。

#1～8 半角スペース

半角スペースについては、以下の2パターンを用意しました。
　
判りづらいですが、右は先頭に半角スペースがあります。
2パターンを、以下のビジュアルを対象に試行します。
・テキストボックス
・インサイト
・グラフタイトル
・コントロールタイトル

※インサイトはデフォルトで式が入りますが
すべて削除し、テキストボックスと同様の見た目となるようにしています。

#9～12 環境依存文字

「①②③」等の環境依存文字を以下のビジュアルで使用し、試行します。
・テキストボックス
・インサイト
・グラフタイトル
・コントロールタイトル

#13 一意の値による集計-ツールチップ

黄色でマークした「個別の値をカウント」の有無により、移行が可能か否かを確認します。
参考として、比較対象は右の設定です。

#14 個別の値カウントによる集計

テーブルにおいて、「個別の値をカウント」を使用します。

#15～20 削除済みパラメータ・フィールド

削除済のパラメータ・およびフィールドがどのように影響するかを調べます。
これらを使用した計算フィールドやフィルタを作成し、使用したフィールド・パラメータを削除することで、検証します。
計算フィールドについては、ビジュアルへの使用あり・なしをそれぞれ確認します。
#15,#17,#18,#20については、ビジュアルでエラーが出た状態となるので、移行時のエラーが出ることが正となります。

#21,22 データ型・カラム数

移行前後で参照するデータセットが変わるように、定義情報の書き換えの手順を挟みます。
いずれも移行時にエラーが出ることが正となります。

#23～26 jsonの書き換え検証

取得した定義情報に対して、紐づけるデータセットや使用するフィールド名などを書き換えます。
また、ビジュアルの情報やパラメータを追記することで、生成された分析に追加されているかを検証します。

検証の流れ

検証の流れは以下の通りです。
③、⑤でAPIを使用して定義ファイル(json形式)の取得や新規分析の作成を実施します。
※手順はこちらのワークショップの手順を参考にしました。

① 事前準備
② 検証用の分析の作成
③ ②の分析の定義ファイルをjson形式で出力
④ ③で取得した定義情報の書き換え
⑤ ④をもとに新しい分析の作成

①事前準備

API操作はAWS CLIで実施するためCLIを準備します。
ここでは今回の検証のための特別な準備はありませんので詳細は割愛しますが、
実施内容は以下の通りです。
・CLIインストール
・認証情報の設定
・セッショントークンの発行

②検証用の分析の作成

検証内容に応じて分析を作成します。
※ここも分析の作成自体は特別なことはありませんので手順は割愛します。

③分析の定義ファイルを出力

次のコマンドをCLIで実行していきます。
なお、以降実行する各コマンド内の変数は事前に定義しています。
QUICKSIGHT_REGION：リージョン(ap-northeast-1)
AWS_ACCOUNT_ID：AWSアカウントID
QUICKSIGHT_ANALYSIS_ID：②で作成した分析ID
QUICKSIGHT_ANALYSIS_DEFINITION_FILE_PATH：分析定義ファイルの出力先フォルダパス
QUICKSIGHT_ANALYSIS_SKELETON_FILE_PATH：スケルトンファイルのフォルダパス
QUICKSIGHT_NEW_ANALYSIS_DEFINITION_FILE_PATH：新規作成される分析定義ファイルのパス

②で作成した分析の定義ファイルの取得
aws --region %QUICKSIGHT_REGION% quicksight describe-analysis-definition --aws-account-id %AWS_ACCOUNT_ID% --analysis-id %QUICKSIGHT_ANALYSIS_ID% > %QUICKSIGHT_ANALYSIS_DEFINITION_FILE_PATH%

スケルトンファイルの取得
※スケルトンファイル=定義項目のみを記載したテンプレートファイルのようなもの
aws --region %QUICKSIGHT_REGION% quicksight create-analysis --generate-cli-skeleton > %QUICKSIGHT_ANALYSIS_SKELETON_FILE_PATH%

新しい分析定義ファイルの作成
※taskforce_AssetasCode.py=取得した定義情報を加工してスケルトンファイルから新しい分析定義ファイルを作成するスクリプト
python taskforce_AssetasCode.py --account-id %AWS_ACCOUNT_ID% --in-definition %QUICKSIGHT_ANALYSIS_DEFINITION_FILE_PATH% --in-skeleton %QUICKSIGHT_ANALYSIS_SKELETON_FILE_PATH% --out-file %QUICKSIGHT_NEW_ANALYSIS_DEFINITION_FILE_PATH%

新しい分析IDを変数化
set QUICKSIGHT_NEW_ANALYSIS_ID={AnalysisId}

④定義情報の書き換え

検証内容に応じて、new_definitionファイルの情報を手動で書き換えます。

⑤新しい分析の作成

生成した分析定義ファイルから新しい分析を作成します
aws --region %QUICKSIGHT_REGION% quicksight create-analysis --cli-input-json file://%QUICKSIGHT_NEW_ANALYSIS_DEFINITION_FILE_PATH%

>aws --region %QUICKSIGHT_REGION% quicksight create-analysis --cli-input-json file://%QUICKSIGHT_NEW_ANALYSIS_DEFINITION_FILE_PATH%
{
    "Status": 202,
    "Arn": "arn:aws:quicksight:ap-northeast-1:000000000000:analysis/a0b9be5c-b20e-4d9d-b3ed-97084819a222",
    "AnalysisId": "a0b9be5c-b20e-4d9d-b3ed-97084819a222",
    "CreationStatus": "CREATION_IN_PROGRESS",
    "RequestId": "caebe0c7-8f84-41d9-badd-fdc472788a9d"
}

ステータス確認
aws --region %QUICKSIGHT_REGION% quicksight describe-analysis --aws-account-id %AWS_ACCOUNT_ID% --analysis-id %QUICKSIGHT_NEW_ANALYSIS_ID%

>aws --region %QUICKSIGHT_REGION% quicksight describe-analysis --aws-account-id %AWS_ACCOUNT_ID% --analysis-id %QUICKSIGHT_NEW_ANALYSIS_ID%
{
    "Status": 200,
    "Analysis": {
        "AnalysisId": "a0b9be5c-b20e-4d9d-b3ed-97084819a222",
        "Arn": "arn:aws:quicksight:ap-northeast-1:000000000000:analysis/a0b9be5c-b20e-4d9d-b3ed-97084819a222",
        "Name": "テスト分析",
        "Status": "CREATION_SUCCESSFUL",
        "DataSetArns": [
            "arn:aws:quicksight:ap-northeast-1:000000000000:dataset/93f740ef-f24e-4739-b28b-a382678e5b11"
        ],
        "ThemeArn": "arn:aws:quicksight::aws:theme/CLASSIC",
        "CreatedTime": "2023-09-05T12:14:49.068000+09:00",
        "LastUpdatedTime": "2023-09-05T12:14:49.402000+09:00",
        "Sheets": [
            {
                "SheetId": "7f54ec48-8f00-41d9-9e40-6fb98c01fc25",
                "Name": "シート 1"
            }
        ]
    },
    "RequestId": "caebe0c7-8f84-41d9-badd-fdc472788a9d"
}

Statusの値が「CREATION_SUCCESSFULL」になっていれば作成成功です。

以上で既存分析から新規分析を作成する作業は完了です。

検証結果

検証結果は以下の通りとなりました。

実行結果：検証実行時の成功可否
検証結果：検証としての成功可否

#1～8の半角スペースについては、先頭に空白がある場合、英字・日本語(漢字)表記関わらずエラーとなるようです。これらは作成後のエラーではなく、定義情報取得(describe-analysis-definition)が不可であることを確認しました。
全件試行はしていませんが、全角スペースではエラーは確認されませんでした。

#9～12の環境依存文字については、使用文字によって可否が変わる可能性が考えられます。
使用頻度の高い①②などの丸数字はOKでしたが、試しに1⃣2⃣3⃣で実施したところエラーとなってしまいました。
今回の検証ではこの2種類のみ確認しましたが、他にもNGになる種類はあるのではと考えられます。

#13の「一意の値」については、ツールチップの特定の設定値に原因があるようです。

マップや散布図など、複数のビジュアルでのツールチップを試行しましたが、全て同様にエラーとなりました。
なお、これらのエラーは「CREATION_FAILED」で返らず、当該オブジェクトのみがエラーとなります。
以下のような表示です。

#15～20の削除済みパラメータ・フィールドについてはおおむね想定通りです。
ただし、#16や#19等のビジュアルに使用していない場合についてもエラーとなるのは想定外でした。
これらは手動で(Quicksightコンソール上から)複製することは可能です。
本手順で複製や移行を行う場合には、使用していない項目を精査する必要があり、不便さも感じる結果となりました。

#21,22のような、データセットと齟齬が生じる場合のエラーは、想定通りの結果です。

#23～26のように定義ファイルであるjsonの書き換えを行う事は、概ね問題なさそうです。
ただし、連動して書き換える必要のある項目などは判りづらい印象がありました。
複雑な書き換えを手動で行う場合は、エラーの要因となるような設定ミスに細心の注意を払う必要があります。

おわりに

今回はエラー発生有無の確認が主な検証となりましたが、本機能の活用想定として、
既存のダッシュボードをベースに類似のダッシュボードを作成するケースなどで効率的だと感じました。
（jsonの書き換えが可能なため、部分的に変更したダッシュボードを複数作成する場合など）
また、定義情報を出力できることで、オブジェクト管理にも役立てられそうだなと感じましたので、
実務でQuickSightを使用する方はぜひ活用を検討してみてください。

株式会社ジールでは、初期費用が不要で運用・保守の手間もかからず、ノーコード・ローコードですぐに手元データを分析可能なオールインワン型データ活用プラットフォーム「ZEUSCloud」を提供しております。
ご興味がある方は是非下記のリンクをご覧ください：
https://www.zdh.co.jp/products-services/cloud-data/zeuscloud/

QuicksightのAsset as Codeのエラー要因を探る