Amazon QuickSight BIOps – パート2 : API を使用したバージョン管理

本記事は、2025年8月6日に公開された Amazon QuickSight BIOps – Part 2: Version control using APIs を翻訳したものです。翻訳は ProServe Data Analytics Consultant の西澤祐介が担当しました。

この記事では、API駆動のビジネスインテリジェンスオペレーションズ（BIOps）フレームワークの概要を説明します。このフレームワークは、手作業による負荷を軽減し、Amazon QuickSightにおけるライフサイクル管理を改善することを目的としています。

ビジネスインテリジェンス (BI) 環境が複雑化する中で、ダッシュボード、データセット、デプロイといった作業を手動で管理していると、結果の不整合、バージョンのずれ、コラボレーションの効率低下といった課題につながりがちです。データから得られるインサイトの提供をスケールさせ、ガバナンスを強化し、そして開発、QA（品質保証）、本番といった各環境の信頼性を高める上で、自動化は極めて重要になります。

DevOps は、ソフトウェア開発と IT 運用を統合することで、デリバリーを加速し、信頼性を向上させるための考え方です。ソフトウェアのワークフローを合理化し、スケールさせるために、DevOps では以下のプラクティスが重視されます。

継続的インテグレーションと継続的デリバリー（CI/CD）
Infrastructure as Code (IaC) と Assets as Code (AaC)
自動化
モニタリング
コラボレーションツール（Git、Jira、Slackなど）

BIOps は、これらの原則を BI のワークフローに応用したものです。アセットのバックアップ、バージョン管理、デプロイを自動化することで、BI チームはダッシュボード、データセット、分析を、一貫性を高め、トレーサビリティを向上させ、より効率的に管理できるようになります。

このブログシリーズでは、皆様が QuickSight で BIOps のプラクティスを実装し、よりスケーラブルで信頼性の高い BIOps を実現するための方法について解説します。パート1では、ノーコードでのバージョン管理とコラボレーションに関するガイドを提供しました。この記事では、QuickSight API を使用してバージョン管理とロールバックを自動化し、BI アセットのための CI/CD パイプラインを構築する方法について解説します。そしてパート3では、クロスアカウントおよびマルチ環境でのデプロイ、競合の検出とガバナンスについて取り上げます。

ソリューションの概要

この記事では、QuickSight における API ベースの BIOps ソリューションの概要を解説し、チームがプログラムによって制御する手法で BI アセットのバージョン管理、デプロイ、ガバナンスを自動化する方法を紹介します。BI エンジニア、DevOps リード、そしてプラットフォーム管理者の方々は、この記事で紹介するコードベースのプラクティスを実践することで、BI ワークフローをスケールさせることができます。

前提条件

このチュートリアルを進めるにあたり、以下の前提条件が必要です。

AWS アカウント
以下の AWS サービスへのアクセス権:
- AWS CloudFormation
- Amazon QuickSight
- Amazon Simple Storage Service (Amazon S3)
- AWS Identity and Access Management (IAM)：QuickSight のTemplate, Assets-as-Bundle, Create, Update, Delete, Describe APIを利用できる権限が必要です。
Python の基本的な知識（Python 3.9 以降を推奨）
SQL の基本的な知識
最新バージョンの AWS Command Line Interface (AWS CLI) がインストール済みであること
Boto3 がインストール済みであること

また、このチュートリアルを始める前に、シリーズのパート1を確認しておくことをお勧めします。

QuickSight アセット API の概要

QuickSight は、BI アーティファクトを管理するための API ベースのアプローチを複数提供しています。バージョン管理、デプロイの自動化、バックアップといった目的に応じて、それぞれ強みの異なる API を使い分けることができます。

主なアプローチは以下の3つです。

Template API (旧来の方法)
Assets-as-Bundle API (新しい方法)
Describe-Definition API

これら3つのアプローチは、いずれもダッシュボード、分析、データセットなどをプログラムで扱うことを可能にしますが、可視性、制御性、そして最新の CI/CD ワークフローとの親和性において大きく異なります。

Template API

「テンプレート」ベースのアプローチは、CreateTemplate や CreateDashboard といった API を利用し、AWS アカウントや AWS リージョンをまたいで QuickSight のアセットを移行するための従来からの手法でした。従来、「テンプレート」はダッシュボードのバックアップや、他の環境へのアセットのデプロイに使用されてきました。初期の実装では、「テンプレート」の中身は不透明で、BIチームにとっては完全なブラックボックスでした。しかし、DescribeTemplateDefinition API の登場により、チームは「テンプレート」のJSON 定義を抽出して、内容の確認やバックアップを行えるようになりました。とは言え、「テンプレート」は新しい他の方法に比べて柔軟性に欠け、反復的な開発、フィールドレベルでの編集、あるいはバージョン管理といったワークフローには最適化されていません。

それでも、Git リポジトリや S3 バケットといった外部のバージョン管理システムやストレージをセットアップせずに、QuickSight 環境内にバックアップを保存したいと考える BI チームにとっては、「テンプレート」は依然として有用です。このため、製品内でのアセット管理を中心に行いたいチームにとって、「テンプレート」は手軽な選択肢となります。

QuickSight アセットに関する Template API の全リストは以下の通りです。

CreateTemplate
DeleteTemplate
DescribeTemplate
DescribeTemplateDefinition
UpdateTemplate
UpdateTemplatePermissions

Assets-as-Bundle API

CI/CDパイプラインを導入したり、IaC を実践したりしているチームにとって、モダンな Assets-as-Bundle API と Describe-Definition API は、より高い透明性、柔軟性、そして制御性をもたらします。そのため、今日の多くのエンタープライズ向けのユースケースにおいて推奨されるアプローチとなっています。

Assets-as-Bundle API は、よりモジュール化され、ポータビリティの高いデプロイの選択肢を提供します。この API は、QuickSight のダッシュボードや分析、そしてそれらに関連するアセット（データセット、データソース、テーマ、フォルダ）を、ZIP アーカイブ、または AWS CloudFormation テンプレートとしてエクスポートします。エクスポートされたアーカイブを展開すれば、アセットのメタデータを JSON ファイルとして確認することは可能ですが、それには手間がかかり、きめ細かいバージョン管理には理想的ではありません。さらに、複数のダッシュボードをエクスポートする際には、複数のバンドル間でデータセットが重複し、冗長な形で含まれてしまう可能性があります。QuickSight のインポート処理はこれらの重複を適切に処理し、意図しない上書きを防いでくれますが、やはりこの手法は、詳細なバージョン管理というよりは、関連アセットをまとめてデプロイする用途に適しています。

ソースアカウントからバンドルファイルをエクスポートするジョブの開始、追跡、詳細確認には、以下の API を使用します。バンドルファイルとは、呼び出し元が指定したアセットと、オプションでそのアセットが依存するすべてのリソースを含む ZIP ファイル（拡張子は .qs ）のことです。

StartAssetBundleExportJob – アセットバンドルファイルをエクスポートするための非同期 APIです。
DescribeAssetBundleExportJob – エクスポートジョブのステータスを取得するための同期 APIです。成功した場合、レスポンスにはバンドルを取得するための署名付き URL が含まれます。
ListAssetBundleExportJobs – 過去のエクスポートジョブを一覧表示するための同期 API です。リストには、過去15日間の完了したジョブと実行中のジョブが両方含まれます。

以下の API は、バンドルファイルを入力として受け取り、ターゲットのアカウントでアセットを新規作成または更新するインポートジョブの開始、追跡、詳細確認を行います。

StartAssetBundleImportJob – アセットバンドルファイルのインポートを開始するための非同期 API です。
DescribeAssetBundleImportJob – インポートジョブのステータスを取得するための同期 API です。
ListAssetBundleImportJobs – 過去のインポートジョブを一覧表示するための同期 API です。リストには、過去15日間の完了したジョブと実行中のジョブが両方含まれます。

Describe-Definition API

`Describe-Definition API` は、各アーティファクトの内部的な JSON 構造を、透過的かつフィールドレベルのフォーマットで公開します。この定義ファイルは Git で追跡したり、プルリクエストを通じてレビューしたり、対応する Update API で更新したりすることが可能です。そのため、CI/CD パイプラインや IaC プラクティスとの統合に最適な手法と言えます。主なトレードオフは、データセットやデータソースといった依存関係を個別に扱う必要がある点です。これらはダッシュボードや分析の定義には自動でバンドルされないためです。

Describe-Definition API には以下が含まれます。

DescribeDataSource
DescribeDataSet
DescribeAnalysisDefinition
DescribeDashboardDefinition

実際の現場では、多くの BI チームは両方のアプローチを併用しています。アセットをまとめてデプロイする際には Assets-as-Bundle を、そして、きめ細かいバージョン管理や反復開発には Describe-Definition を利用する、といった使い分けです。それぞれの API をいつ使うべきか理解することで、ガバナンスの強化、監査性の向上、そして環境間でのスムーズなアセットの移行が可能になります。

各手法の比較

以下の表は、これら3つの API 手法の主なユースケースとデータの保管場所をまとめたものです。

手法	主なユースケース	用途	保管場所
Template API	製品内でのバックアップ、レガシーなデプロイ	UI 中心のチーム、シンプルなバックアップ	QuickSight 内
Describe-Definition API	きめ細かいバージョン管理と自動化	CI/CD、Git との連携	Git, Amazon S3, コードリポジトリ
Assets-as-Bundle API	依存関係を含めた環境単位のデプロイ	開発環境から本番環境への展開、一括移行	Amazon S3, ローカルのZIPアーカイブ

QuickSight APIに関するより詳細な情報については、QuickSight API リファレンスや Boto3 QuickSight ドキュメントをご参照ください。

BI アーティファクトのバージョン管理におけるベストプラクティス

これ以降のセクションでは、単一アカウント内でのダッシュボードのバージョン管理に関するベストプラクティスを解説します。

QuickSight において、「ダッシュボード」は他の人が見れるように設定された、「分析」のスナップショットです。一方、「分析」は、BI チームが開発や改善を繰り返すための作業用アセットです。QuickSight の UI 上では、バージョン管理機能は「ダッシュボード」に対してのみ提供されています。これは、「分析」がエンドユーザーに公開されることはなく、常に開発中のものと見なされているためです。

しかし、Describe-Definition APIのようなプログラム的な手法を用いると、分析の各要素（フィルター、計算フィールド、ビジュアル、パラメーターなど）を、モジュール化されたコードブロックとして扱うことができます。これにより、チームは構造化されたコード駆動の方法で「分析」を管理し、バージョンを記録していくことが可能になります。結果として、複数の作成者が並行して共同作業を進められるようになります。そのため、Describe-Definition APIを利用する際には、「分析」自体のバージョン管理も重要なプラクティスであると我々は考えています。

Template API を利用したバージョン管理

以前のブログ記事「BIOps: Amazon QuickSight object migration and version control」では、テンプレートベースのアプローチを用いて QuickSight のダッシュボードのバージョン管理を実装する方法を解説しました。その記事の執筆時点では、「テンプレート」が、「ダッシュボード」のバージョン管理を行うための唯一利用可能なメカニズムでした。

次の図は、そのソリューションで用いたアーキテクチャを示したものです。

このワークフローは以下のステップで構成されます。

まず、BI 開発者が「分析」を作成し、それに基づいて「テンプレート」を保存します。これらがバージョン1のアセットとなります。
この「分析」は「ダッシュボード」として公開され、QA チームがこのバージョン1の「ダッシュボード」に対してテストを実施します。
QA テストの後、BI 開発者は「分析」の改修を続け、バージョン2を構築します。
更新された「分析」は、バージョン2の「ダッシュボード」として公開されます。
QA チームはバージョン2の「ダッシュボード」をテストし、結果に応じて以下のアクションのいずれかを実行します。
1. テストに合格した場合： BI 管理者は「テンプレート」を更新し、バージョン2の内容を反映させます。
2. 問題が発見された場合： BI 開発者は分析上で修正を試みます。
  1. 問題が修正可能な場合、バージョン2の開発が継続されます。
  2. 問題が修正不可能な場合、BI 管理者はバックアップ用の「テンプレート」を使ってバージョン1にロールバックできます。
QuickSight には、作成者がセッション中に以前のバージョンに戻せる Undo 機能があります。もし Undo の履歴がリセットされた場合（例えばデータセットの置換など）、あるいは以前に安定版として確認済みの状態へのロールバックが必要になった場合は、BI 管理者はバージョン1の「テンプレート」と UpdateAnalysis API を使って分析を復元できます。
BI 開発者は、この復元されたバージョン1の「分析」をベースに作業を再開し、次の安定バージョンを目指して開発サイクルを繰り返します。

Describe-Definition API を利用したバージョン管理

次の図は、Describe-Definition APIと CreateまたはUpdate APIを利用して、QuickSight アセットのバージョン管理を実装するためのアーキテクチャを示したものです。

ワークフローは以下のステップで構成されます。

アセットの作成と保存
1. BI チームは、Describe-Definition APIのレスポンス構文を参考に、プログラムで QuickSight アセットの構築を開始できます。ダッシュボードや分析は、シート、計算フィールド、ビジュアル、フィルター、パラメーターといった JSON ベースの構成要素を使って構築可能です。同様に、データセットも物理テーブルと論理テーブルのマッピングを定義する JSON 構造を用いて作成できます。QuickSight のアセットは構造化された JSON 形式に従っているため、コード駆動の開発に適しています。
2. 学習のハードルを下げるために、まず QuickSight コンソールを使ってアセットを作成し、その設定が要件を満たしていることを確認した上で、Describe-Definition APIでアセットの定義を抽出する方法もあります。抽出した JSON 定義は、Git、Amazon S3、あるいは社内のコードリポジトリといったバージョン管理が可能な場所に保存できます。これは、UI ベースの開発からコード駆動の開発へスムーズに移行するのに役立ちます。
3. チームが既に本番環境にアセットをデプロイ済みで、そこからプログラムによるワークフローに移行したい場合は、本番アカウントから直接Describe-Definition APIで定義を抽出できます。その定義を開発環境のソースリポジトリ（Git や Amazon S3 など）に保存し、今後の開発やデプロイの起点として利用することが可能です。
JSON 定義のデプロイと可視化
BI チームが JSON 定義の開発を完了したら、CreateまたはUpdate API（CreateDashboard, UpdateAnalysis, UpdateDataSetなど）を使ってアセットをデプロイし、QuickSight コンソール上で直接内容を可視化します。これにより、コードからビジュアルへのシームレスな移行が実現し、バージョン管理されている定義が UI に一貫して反映されるようになります。
テストと本番環境へのデプロイ
開発環境や QA 環境にアセットをデプロイした後、BI チームはテストを実施し、アセットが機能面・ビジュアル面で要件を満たしているか検証します。検証後、テスト済みの定義を同じCreateまたはUpdate APIを使って本番アカウントへデプロイすることで、統制の取れた一貫性のあるリリースプロセスを実現できます。更新された分析を QA という名前のフォルダにデプロイするサンプルコード、QA アカウントへデプロイするサンプルコードを用意してますのでご確認下さい。

以下のサンプルコードは、「分析」の定義を取得し、dev という名前のフォルダにコピーします。これにより、BI チームはアセットをプログラムで開発・管理できるようになります。

def describe_analysis_definition(session, id):
    qs = session.client('quicksight')
    sts_client = session.client("sts")
    account_id = sts_client.get_caller_identity()["Account"]
    try:
        response = qs.describe_analysis_definition(
            AwsAccountId=account_id,
            AnalysisId=id)
    except Exception as e:
        return ('Faild to describe analysis: ' + str(e))
else:	
   return response
try:
    sample_analysis = func.describe_analysis_definition(qs_session, analysisid)
    print('Successfully get sample analysis contents.')
except Exception as e:
    faillist.append({
        "Action": "scenario_1_dev: get sample analysis contents",
        "Error Type": "describe_analysis_contents Error",
        "AnalysisID": analysisid,
        "Name": 'template_1',
        "Error": str(e)
    })
new_id = 'copy_t_1_' + str(int(time.time()))
new_name = 'copy_t_1'
try:
    res = func.copy_analysis(qs_session, sample_analysis, new_id, new_name, 'owner', dev_config["assets_owner"])
except Exception as e:
    faillist.append({
        "Action": "scenario_1_dev: copy analysis",
        "Error Type": "copy_analysis Error",
        "AnalysisID": analysisid,
        "Name": 'template_1',
        "Error": str(e)
    })
time.sleep(20)
status = func.check_object_status('analysis', new_id, qs_session)
print('Copy status of analysis ' + new_id + ' is ' + status)
if status == 'CREATION_SUCCESSFUL':
    res = func.locate_folder_of_asset(qs_session, new_id, dev_config["dev_folder"], 'ANALYSIS')
    print('Successfully copied analysis ' + new_id + ' in dev account/folder.')

以下のサンプルコードは、「分析」を定義し、計算フィールド、パラメーター、フィルターをプログラムで追加するものです。これらの二次的なアセット（計算フィールド、フィルター、パラメーター）は、再利用可能なコードブロックとして共有ライブラリに保存されます。

{
      "most_recent": {
          "DataSetIdentifier": "ds_assets_as_code",
          "Name": "most_recent",
          "Expression": "max({date_time})"
        }
    ,
      "Calculated TimeFrame": {
          "DataSetIdentifier": "ds_assets_as_code",
          "Name": "Calculated TimeFrame",
          "Expression": "datediff(${StartDate},${Enddate},'DD')"
      }
}
"""
Now, please add CalculatedFields
"""
f = open('Assets_as_Code/library/2nd_class_assets/analysis_cf_library.json')
l_cf = json.load(f)
cf_name = 'most_recent'
try:
    res = func.update_analysis(qs_session,new_id, new_name, new_analysis, 'CalculatedFields', l_cf[cf_name])
except Exception as e:
    faillist.append({
        "Action": "scenario_2_dev: add CalculatedFields",
        "Error Type": "update_analysis Error",
        "AnalysisID": new_id,
        "Name": new_name,
        "Error": str(e)
    })
print(cf_name + " is successfully added into analysis " + new_name)
"""
Now, please add parameters (keyword: ParameterDeclarations)
"""
new_analysis = func.describe_analysis_definition(qs_session, new_id)
f = open('Assets_as_Code/library/2nd_class_assets/parameter_library.json')
l_p = json.load(f)
p_name = "StartDate"
try:
    res = func.update_analysis(qs_session,new_id, new_name, new_analysis, 'ParameterDeclarations', l_p[p_name])
except Exception as e:
    faillist.append({
        "Action": "scenario_2_dev: add ParameterDeclarations",
        "Error Type": "update_analysis Error",
        "AnalysisID": new_id,
        "Name": new_name,
        "Error": str(e)
    })
print(p_name + " is successfully added into analysis " + new_name)

ビルド済みの関数群は GitHub で公開されています。ライブラリ、ユーティリティ、設定サンプル、ロギングヘルパーといったその他の補助コードは、以下のディレクトリに格納されています。

次のスクリーンショットは、AaC（Assets as Code）アプローチにおけるサンプルコードのディレクトリ構造を示したものです。パッケージ全体をダウンロードし、独自のAaCソリューションを構築するためのベストプラクティスとしてご活用ください。

このアーキテクチャでは、バージョン管理は Git リポジトリや Amazon S3 のバージョニング機能といった外部の仕組みで扱われます。このアプローチにより、BI チームはアセットを並行開発したり、計算フィールド、フィルター、ビジュアルといった二次的なアセットを再利用したりすることが可能になります。例えば、チームは計算フィールドの定義を、標準化された名前を持つ独立した JSON オブジェクトとして保存できます。これにより、複数の分析やダッシュボードをまたいで再利用できるようになります。この手法のさらなるメリットとしては、プルリクエストによる行単位のコードレビュー、以前のバージョンへの簡単なロールバック、そして CI/CD ワークフローとのシームレスな統合などが挙げられます。

まとめると、このパターンは QuickSight を完全にコード駆動のプラットフォームへと変革し、インフラと BI アセットをコードとして扱うことを可能にします。

QuickSight UI と API を併用したハイブリッドワークフローによるバージョン管理

BI チームは、このアーキテクチャを拡張してハイブリッドモデルを構築することもできます。つまり、開発は QuickSight UI で行い、バージョン管理を API 経由で行うというモデルです。このアプローチでは、チームは QuickSight コンソール上で対話的にアセットの構築や更新を続けます。開発が完了し、アセットがテストに合格したら、チームは Describe-Definition API を使って更新された JSON 定義を抽出し、Git や Amazon S3 といったバージョン管理リポジトリに保存します。

このモデルは、UI ベース開発の容易さと柔軟性を、コードベースのバージョン管理が持つ構造性やトレーサビリティと組み合わせるものです。プログラムによるワークフローへ移行しようとしているBI チームにとっては、まさに両者の良いとこ取りと言えるでしょう。

次の図は、UI ベースの開発とコードベースのバージョン管理が持つ構造性やトレーサビリティを組み合わせたアーキテクチャを示しています。

ワークフローは以下のステップで構成されます。

BI の作成者は、ダッシュボード、分析、データセット、データソース、テーマを QuickSight コンソール上で直接開発します。
開発が完了し、アセットが機能面・ビジュアル面のテストに合格したら、チームは Describe-Definition APIを使ってアセットの定義をエクスポートし、Git やAmazon S3 に保存します。
検証済みのアセットは、CreateまたはUpdate APIを使って本番環境にデプロイされます。
作成者は、次のバージョンに向けてUI 上で同じアセットの開発を再開します。
作成したバージョンはテストされます。
1. テストに合格した場合：リポジトリにあるバージョン管理された JSON 定義を更新し、ステップ6に進みます。
2. テストに失敗した場合：Git や Amazon S3 に保存しておいた以前の定義を使い、Update APIを介して QuickSight UI 上のアセットをロールバックします。
更新された、あるいはロールバックされた定義を本番アカウントにデプロイすることで、安定したバージョン管理下でのリリースを実現します。

Amazon EventBridge を利用した QuickSight のバージョン管理自動化

Amazon EventBridge を利用すると、個々の QuickSight アセット（分析、ダッシュボード、VPC 接続など）やフォルダ構造への変更を、アセットレベルのイベントとしてほぼリアルタイムに捉え、監視することができます。ここで言うイベントには、アセットの作成、更新、削除、フォルダ構成の変更などが含まれます。詳細については、「Automate your Amazon QuickSight assets deployment using the new Amazon EventBridge integration」をご参照ください。

QuickSight と EventBridge を連携させることで、BI チームは特定のアセットやフォルダが変更された際に、後続のワークフロー（例えば AWS Lambda や AWS Step Functions ）を自動的にトリガーするルールを定義できます。これにより、アセット定義のエクスポート、Git や Amazon S3 へのスナップショット保存、監査やロールバックのためのタグ付けといったバージョン管理プロセスがシームレスになります。結果として、チームは手動での介入なしにガバナンスを自動化し、環境間の一貫性を維持できるようになります。

Assets-as-Bundle APIを利用したバージョン管理

Assets-as-Bundle API をバージョン管理に利用することは推奨しません。この API の主なユースケースは、ダッシュボードとその依存関係にあるアセットを環境間で移行（例えば、開発環境から QA、本番環境へ）することです。バンドルファイルは技術的には保存して再利用できますが、きめ細かい追跡、比較、モジュール開発にはあまり適していません。適切なバージョン管理のためには、Describe-Definition API を Git や Amazon S3 ベースのストレージと組み合わせて利用してください。

クリーンアップ

将来的な課金を防ぐため、テスト中に作成した S3 バケット、QuickSight のデータセット、分析、ダッシュボード、その他サンプルスクリプトで利用したアセットなどのリソースは削除してください。

まとめ

この記事で解説した QuickSight API の機能は、BI アセットを大規模に管理するための強力な自動化、ガバナンス、そして柔軟性をもたらします。これらの API により、アセットのライフサイクルを完全にコントロールし、CI/CD パイプラインや Git ベースのワークフロー、カスタムツールとシームレスに連携させることが可能になります。ダッシュボードのバージョン管理、環境をまたいだデプロイ、スキーマ競合の解決などを簡単に行うことができます。

きめ細かい制御、監査性、アカウントやリージョンをまたいだ再現可能なデプロイが必要な場合は、API を利用してください。スピード、使いやすさ、あるいは手軽なイテレーションを優先する場合は、QuickSight コンソールを利用しましょう。多くのチームにとっては、QuickSight コンソールで開発し、変更のキャプチャを API で行うというハイブリッドなアプローチが、両方の長所を活かす最良の方法となるでしょう。

BIOps プラクティスを導入することで、BI チームはデリバリーをスケールさせ、リスクを低減し、一回限りの開発から、信頼性が高く統制の取れたインサイトの創出へと移行することができます。

パート3 では、クロスアカウントおよびマルチ環境でのデプロイ、そして競合の検出とガバナンスについて解説します。

Amazon Web Services ブログ