Amazon Web Services ブログ

Amazon QuickSight BIOps – パート3 : API を使用したアセットのデプロイ

本記事は、2025 年 8 月 6 日に公開された Amazon QuickSight BIOps – Part 3: Assets deployment using APIs を翻訳したものです。翻訳は Solutions Architect の守田 凜々佳が担当しました。

ビジネスインテリジェンス (BI) エコシステムがチーム、アカウント、環境全体に拡大するにつれて、一貫性、信頼性、ガバナンスの維持が大きな課題となります。特にマルチアカウント環境では、ダッシュボードとデータセットを手動でデプロイすることで、バージョンの不一致、依存関係の破綻、運用リスクの増大につながることがあります。

このシリーズの投稿では、Amazon QuickSight におけるビジネスインテリジェンス運用 (BIOps) に焦点を当てています。
パート 1 では、バージョン管理とコラボレーションのノーコードガイドを提供しました。
パート 2 では、QuickSight API を使用した自動バージョン管理とロールバック、そして BI アセットの継続的インテグレーション/継続的デリバリー (CI/CD) パイプラインについて説明しました。本記事では、QuickSight における API を活用した BIOps 戦略に焦点を当て、特に以下のトピックについて説明します：

  • API を使用したクロスアカウントおよび複数環境へのアセットの展開
  • データセットのバージョン更新時における競合の検出と解決
  • 開発、QA、本番環境間での権限と設定の管理

Assets-as-Bundle API、Describe-Definition API、自動化スクリプトなどのツールを使用して、手作業を最小限に抑え、下流での障害を防ぎながら、アセットをプログラムによって自動的にデプロイする方法を説明します。

ソリューションの概要

このシリーズのパート 2 では、QuickSight API を使用したバージョン管理、ロールバック、CI/CD ワークフローについて説明しました。本記事では、その内容を踏まえて、デプロイメントをスケールし、異なる環境間での一貫性を確保するための実践的なテクニックを紹介します。
以下のセクションでは、QuickSight における API ベースの BIOps ソリューションの概要を説明し、チームがプログラムコードを用いて BI アセットのデプロイメントとガバナンスを自動化する方法を紹介します。 QuickSight において複数の AWS アカウント・リージョン間での BI アセットのデプロイ方法について解説し、API を使用してダッシュボード、データセット、および依存関係を一貫性をもって、安全でスケーラブルな形で展開する方法を説明します。

前提条件

このチュートリアルを実施するには、以下の前提条件が必要です。

また、続きを読む前に、このシリーズの パート 1 と パート 2 を確認することをお勧めします。

アセットデプロイメントのためのテンプレート API

「BIOps: Amazon QuickSight object migration and version control」では、テンプレートベースのアプローチを使用して QuickSight アセットをデプロイする方法について説明しています。執筆時点ではテンプレートは環境間でダッシュボードを移行およびバックアップするための主な手段でした。

開発環境と本番環境の 2 つの QuickSight アカウントがあるとします。両方のアカウントは、有効なデータソースに接続するように設定されています。
以下の図は、このアーキテクチャを示しています。

実装の詳細に興味がある場合は、元の記事を参照してください。ただし、現在ではアセットのデプロイメントにテンプレート方式を使用することはおすすめしていません。Assets-as-Bundle や Describe-Definition などの新しい API が導入されたことで、BI チームは QuickSight アセットの管理において、より柔軟で透明性が高く、バージョン管理に適したオプションを利用できるようになりました。

アセットの一括デプロイのための Assets-as-Bundle API

Automate and accelerate your Amazon QuickSight asset deployments using the new APIs では、Assets-as-Bundle API を使用して、AWS アカウントやリージョン間で QuickSight アセットをデプロイする方法について説明しています。これらの API は、ダッシュボード、分析、データセットなど、依存関係のあるアセットのデプロイのために設計されています。

次の図は、このアプローチに基づくサンプルワークフローを示しています。

ExportAssetsBundle API は、QuickSight JSON または CloudFormation テンプレートの 2 つのエクスポート形式オプションを提供します。 QuickSight JSON オプションを使用すると、アセットは各アセットタイプ（分析、ダッシュボード、データセット、データソースなど）に対応した JSON ファイルを含む ZIP ファイルとしてエクスポートされます。
この ZIP パッケージはアセット間の関係を保持し、個々の JSON ファイルの確認や修正がしやすいため、デプロイメントの自動化に適していますが、きめ細かなバージョン管理には適していません。

コンテンツは、次のスクリーンショットに示すような階層構造で整理されています。

このサンプル Jupyter ノートブックでは、QuickSight JSON 形式で、ソースアカウントからターゲットアカウントに QuickSight アセットをデプロイするための ExportAssetsBundle および ImportAssetsBundle API の使用方法を示すワークフローを提供しています。このサンプルは基本的なユースケースとなり、ソース管理の統合、バージョンタグ付け、環境固有の設定などの自動化ステップを組み込んだ包括的なデプロイメントパイプラインに拡張することができます。

アセットデプロイメントにおけるアクセス許可の管理

デフォルトでは、エクスポートされた QuickSight アセットは、エクスポート操作時に include-permissions オプションが明示的に有効化されていない限り、ユーザーレベルまたはグループレベルの権限は保持されません。
権限が含まれている場合でも、ソース環境とターゲット環境の両方でユーザー名またはグループ名が一致していない限り、アカウント間で正しくマッピングされない可能性があります。

適切なアクセス制御のために、インポートジョブの完了後に適切な UpdatePermissions API を使用して、アセットのアクセス権限を手動で更新することがベストプラクティスです。
これにより、ターゲット環境の正しいユーザーまたはグループが、インポートされたダッシュボード、分析、データセット、その他のアセットにアクセスできるようになります。

もう 1 つの選択肢は、StartAssetBundleImportJob API の OverridePermissions パラメータを使用して、インポート時にアクセス許可を割り当てることです。インポートされたアセットへのアクセス権を付与する必要があるターゲットアカウントのユーザーまたはグループを指定できます。
ただし、このオプションは慎重に使用する必要があります。インポートジョブが完了すると、指定されたユーザーまたはグループは直ちにアセットにアクセスできるようになります。意図しないユーザーに機密性の高いダッシュボードやデータセットが公開されることを防ぐため、アクセス許可が正しく設定されていることを確認することが重要です。

環境固有の設定を使用したアセットデプロイメントの管理

StartAssetBundleImportJob API には OverrideParameters というパラメータも用意されており、BI チームはこれを使用してインポート時に環境固有の設定を上書きできます。
これには、Virtual Private Cloud (VPC) 接続、データソースの資格情報、その他のデプロイメント固有の属性などが含まれます。

OverrideParameters を使用することで、エクスポートされたバンドルファイルを直接変更することなく、新しいアカウントや環境にインポートされたアセットが正しいインフラストラクチャリソースに確実に接続できるようにします。
これは特に、ネットワークや認証設定が異なる環境間 (例えば、開発環境から本番環境) でアセットを昇格させる際に便利です。

環境やアカウント間でのアセットのデプロイデプロイメントに関するより包括的なアーキテクチャについては、Guidance for Multi-Account Environments on Amazon QuickSight を参照してください。
このガイダンスでは、開発、検証、本番アカウントの体系的な管理、QuickSight の名前空間とアクセス許可の管理、自動化されたアセットデプロイパイプラインの実装について、企業のシステムに求められるガバナンスおよびスケーラビリティの要件を考慮したベストプラクティスを説明しています。

次の図は、このオプションのソリューションアーキテクチャを示しています。

Assets-as-Bundle API の CloudFormation テンプレートオプションは、機能的には QuickSight JSON オプションと似ています。
このオプションを選択すると、エクスポート出力は、ダッシュボードまたは分析と、データセット、データソース、テーマ、フォルダなどの依存関係をカプセル化した CloudFormation テンプレートになります。このオプションは、既に AWS CloudFormation をインフラストラクチャの自動化に使用しているチームにとって特に有用です。なぜなら、一貫したツールとデプロイメントパイプラインを使用して、他の AWS リソースと共に QuickSight アセットをデプロイおよび管理できるためです。

実践的な例として、Assets-as-Bundle API の CloudFormation テンプレートオプションを使用した一連のワークフローを示すサンプル Jupyter ノートブックをご参照ください。
このノートブックでは、CloudFormation テンプレートを使用して、構造化された再現可能な形でアセット昇格を実現するために QuickSight のアセットをアカウント間でエクスポートおよびデプロイする方法を示しています。

以下の表は、CloudFormation テンプレートを用いる方法と QuickSight JSON (Assets-as-Bundle API) を用いる方法を比較したものです。

項目 CloudFormation テンプレート QuickSight JSON
エクスポート形式 YAML/JSON 形式の CloudFormation テンプレート ZIP アーカイブ内の構造化された JSON ファイル
目的 AWS CloudFormation ベースの Infrastructure as Code (IaC) ワークフローとの統合 QuickSight ネイティブ形式でのアセットの移植性と検査の簡素化
対象範囲 ダッシュボード、分析、および依存関係を含む ダッシュボード、分析、および依存関係を含む
変更可能性 AWS CloudFormation の構文知識が必要；より厳格 読み書きが容易；JSON は QuickSight の内部構造に従う
デプロイメント方法 CloudFormation スタックを使用してデプロイ ImportAssetsBundle API を使用してインポート
開発ツールの互換性 AWS CloudFormation ベースの環境に最適 JSON ベースのワークフローまたはカスタムデプロイメントスクリプトに最適
可読性 BI ユーザーにとって直感的ではない；インフラ指向 BI チームにとってより直感的；Describe API と密接に連携
ユースケースの適合性 BI アセットのデプロイメントを広範な IaC テンプレートに統合するチーム向け QuickSight アセットの移行やコードベースのワークフローに焦点を当てたチーム向け

Assets-as-Bundle API で利用可能な QuickSight JSON と CloudFormation テンプレートのオプションについて詳しく比較するには、Choosing between the two export options of the Amazon QuickSight asset deployment APIs をご参照ください。
この記事では、それぞれのオプションの長所と短所について詳しく説明し、実際の例を示しながら、BI チームがデプロイメントワークフローと自動化のニーズに最適なフォーマットを選択できるようにサポートします。

Automate your Amazon QuickSight assets deployment using the new Amazon EventBridge integration では、Assets-as-Bundle API を Amazon EventBridge と連携してデプロイメントワークフローを自動化する方法を説明しています。 QuickSight アセットの作成、更新、削除などのイベントに応答する EventBridge ルールを設定することで、チームは環境間でアセットのエクスポート、バージョン管理、昇格を行うワークフローを自動的にトリガーできます。この連携は、QuickSight の BI アセットに対してイベントドリブンの CI/CD パイプラインを実現する上で特に有用です。

アセットの段階的なデプロイのための Describe-Definition API

このシリーズの パート 2 では、Describe-Definition API を使用して、単一の QuickSight アカウント内でバージョン管理を行う方法について説明しました。
同じ原則をマルチアカウント構成に拡張することで、環境全体で BI アセットの体系的かつ選択的なデプロイが可能になります。

個々のアセットのデプロイに Describe API を使用することは、多くのシナリオでベストプラクティスとされています。例えば、関連するダッシュボードを更新せずに本番アカウントのデータセットの問題を修正するための緊急デプロイを実行する場合や、依存アセットに影響を与えずにダッシュボード内のフィルター定義を更新する場合などです。このきめ細かな制御により、デプロイのリスクを軽減し、不要な上書きを回避し、大規模な BI 環境における段階的な開発ワークフローとの整合性を保つことができます。

サンプルコードについては、QuickSight アセットのデプロイに関する 2 つの一連の自動化オプションを説明している BIOps: Amazon QuickSight object migration and version control を参照してください。
この記事は元々テンプレートベースのアプローチに基づいていましたが、基本的な概念は今でも有用です。

関連する GitHub リポジトリ で提供されているコードを再利用および応用することができます。
従来のテンプレート関連の API 呼び出しを、新しい DescribeDashboardDefinition やその他の Describe-Definition API に更新することで、バージョン管理されたリソースのデプロイに関する現在のベストプラクティスに沿って、同じ自動化ワークフローを拡張できます。

API メソッドの比較

以下の表は、Assets-as-Bundle API と Describe-Definition API の使用を比較したものです。

比較項目 Assets-as-Bundle API Describe-Definition/Describe API
主なユースケース 環境、アカウント、リージョン間での関連アセットのデプロイ バージョン管理、モジュール開発、CI/CD 統合
粒度 依存関係 (データセット、ソース、テーマ、フォルダ) を含むダッシュボードと分析を完全にバンドル 個別のアセット定義に焦点を当てる
可視性 ZIP ファイルに埋め込まれた JSON または CloudFormation テンプレート；追加作業を要して内容確認が可能 API を通じて直接アクセス可能な、完全に可視化された行単位の JSON 定義
バージョン管理との適合性 理想的ではない；差分の確認、モジュール化、レビューが困難 優れている；Git ベースのワークフロー、レビュー、ロールバックに適している
コンポーネントの再利用性 限定的；バンドルは自己完結型で、複数バンドルのシナリオではデータセットが重複する可能性がある 高い；適切に設計されたソリューションでは、コンポーネント (計算フィールド、フィルター) をアセット間で再利用およびモジュール化できる
開発ワークフロー QuickSight の既存のダッシュボードまたは分析からバンドルを作成 JSON をプログラムで作成または変更し、Update API を使用して適用
デプロイメントワークフロー ExportAssetsBundle を使用してエクスポートし、ImportAssetsBundle を使用してインポート Create または Update API を使用して変更をプッシュ
最適な用途 環境間でのダッシュボードとその依存関係をパッケージとして移行する場合 反復的な開発、CI/CD、コードベースの作業を行う BI チーム向け
制約 バンドルが大きく、冗長なアセットが含まれる可能性がある；個別のコンポーネントの分離や編集が困難 依存アセット (データセット、ソース、テーマ) は含まれず、別途処理が必要

バックアップ、リストア、ディザスタリカバリ

このセクションでは、QuickSight API を使用して BI アセットのバックアップ、リストア、リカバリを行い、信頼性の高いディザスタリカバリを実現し、環境全体でのデータ損失を最小限に抑える方法について説明します。

QuickSight アセットのバックアップ、リストア、ディザスタリカバリには、Assets-as-Bundle API と Describe-Definition API の両方を使用できます。
アセットを定期的にバンドル (ZIP ファイルまたは CloudFormation テンプレート) または個別の JSON 定義としてエクスポートすることで、BI チームは Amazon S3、Git、その他のリポジトリに保存されるバージョン管理されたバックアップを作成できます。

Assets-as-Bundle API を使用すると、チームはダッシュボードごとにバックアップを整理し、各ダッシュボードをその依存関係 (データセット、データソース、テーマなど) と共にエクスポートできます。このアプローチは便利で、ダッシュボード単位でのリカバリに適しています。

一方、Describe-Definition API はより柔軟性が高いものの、より多くの労力を必要とします。
BI チームは、すべてのアセットを個別にリストアップし、タイプ別 (データソース、データセット、分析) に保存し、モジュール式のバックアップ構造を維持できます。確実な復元のためには、データソースから始まり、データセット、テーマ、最後にダッシュボードと分析という依存関係を意識した適切な順序でアセットを再デプロイする必要があります。

前述のとおり、記事 BIOps: Amazon QuickSight object migration and version control では、テンプレートベースのアプローチを使用して QuickSight アカウントのアセットをバックアップおよび復元するためのサンプル実装を提供しています。関連する Jupyter ノートブック では、アカウント全体でのアセットの一括エクスポートとインポートを自動化する方法を説明しています。

もともとはテンプレートを中心に構築されていましたが、関連する API 呼び出しを Describe-Definition API に置き換えることで、現在のベストプラクティスに沿った、スケーラブルで保守可能なバックアップおよび復元ワークフローを作成できます。

さらに、チームは QuickSight フォルダを使用してバックアップを整理し、関連するアセットを構造化された復旧戦略の一部としてグループ化することで、より直感的に復元の操作を管理できます。フォルダベースのバックアップと復元のアプローチについては、こちらの サンプル Jupyter ノートブック を参照してください。このノートブックでは、フォルダで整理された QuickSight アセットのエクスポートと再インポートの方法を示しており、BI チームが関連するアセット (ダッシュボード、分析、データセット) をグループ化して一括管理できるようになっています。

データセットとダッシュボード間のマージコンフリクトの解決方法

このセクションでは、QuickSight でデータセットとダッシュボード間のマージのコンフリクトを検出し解決する方法について説明し、スキーマの変更が依存する可視化やフィルターを壊さないようにする方法を解説します。
次の図は、データセットのバージョン管理とコンフリクト解決のワークフローを示しています。

このプロセスは初期データセット (v1) から始まり、フィールドの名前変更やデータ型の変更などの更新が発生したかどうかを評価します。更新が検出されると、データセットはバージョン 2 (v2) に進み、潜在的なマージのコンフリクトをチェックします。コンフリクトが見つかった場合、フィールドマッピング（例えば、名前が変更されたフィールドを再マッピングしてビジュアルを復元する）によって解決できるかどうかを判断します。コンフリクトが解決可能な場合、影響を受けたアセットを復旧するためにマッピングが適用されます。解決できない場合（例えば、データ型の変更による場合）、サンプルコードを使用して変更されたフィールドを自動的に検出し、未解決の変更によって破損したフィルターやビジュアルをクリーンアップできます。

データセットのマージのコンフリクトを検出して処理するためのサンプルコードは、以下の Jupyter ノートブック で入手できます。このノートブックでは、変更されたフィールドを自動的に特定し、フィールドのデータ型の変更などの単純なマッピングの問題を解決し、互換性のない変更によって破損したフィルターをクリーンアップする方法を示しています。

さらに、QuickSight データセットの更新時にマージのコンフリクトの検出を自動化するためのサンプルコードと GitHub Actions ワークフローを提供しました。Python スクリプト compare_quicksight_datasets.py は、データセットのバージョンを比較して、データ型の変更、フィールド名の変更、フィールドの追加、フィールドの削除を特定します。

GitHub Actions ワークフロー compare-quicksight.yml は、比較を実行するために自動的にトリガーされます。
比較結果はリポジトリの新しいアーティファクトとして保存され、BI チームが変更内容を確認し、データセットのバージョン昇格時にコンフリクトを自動的に解決するか、手動での対応を行うかの判断を下すことができます。

ワークフローを設定して実行するには、以下のステップを完了してください：

  1. YAML ファイルが正しい GitHub ディレクトリに保存されていることを確認してください。

.github/workflows/compare-quicksight.ymlリポジトリは以下のような構造になっているはずです。

your-repo/
├── .github/
│   └── workflows/
│       └── compare-quicksight.yml 
├── compare_quicksight_datasets.py 
├── ...
  1. 以下の例のように compare-quicksight.yml に有効なトリガーが含まれていることを確認してください。
name: Compare QuickSight Datasets 
 on:
 workflow_dispatch:  # 手動トリガーを許可

この方法により、Actions タブからワークフローを手動で実行できます。

  1. ワークフローファイルをリポジトリにコミットしてプッシュします：
git add .github/workflows/compare-quicksight.yml 
 git commit -m "Add QuickSight dataset comparison workflow"
 git push origin main
  1. GitHub リポジトリのシークレットを追加します：
    1. GitHub リポジトリに移動し、Settings, Secrets and variables, Actions を選択します。
    2. New repository secret を選択します。
    3. 以下のようなシークレットを追加します：
      1. AWS_ACCESS_KEY_ID
      2. AWS_SECRET_ACCESS_KEY
      3. AWS_REGION
      4. QUICKSIGHT_ACCOUNT_ID
      5. NEW_DATASET_ID
  2. ワークフローを実行します：
    1. GitHub リポジトリに移動します。
    2. Actions タブで、Compare QuickSight Datasets を選択します。
    3. Run workflow を選択し、必要な入力情報を提供します。

このユーティリティは、バージョン管理やデプロイメントパイプラインの一部として使用できます。また、BI チームは分析やダッシュボードで影響を受けるビジュアルやフィルターを直接確認して更新することで、手動でコンフリクトを解決できます。

リソースの削除

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

まとめ

QuickSight API の機能により、大規模な BI アセットを管理するための強力な自動化、ガバナンス、柔軟性が実現可能になります。本記事では、クロスアカウントおよび複数環境のデプロイメント、コンフリクトの検出とガバナンスに API を使用する方法について説明しました。本記事のガイダンスを使用して、QuickSight の信頼性が高くコンフリクトを考慮したデプロイメント手法を確立できます。

著者について

Ying Wang は、AWS の Generative AI 組織の Senior Specialist Solutions Architect で、Amazon QuickSight と Amazon Q を専門とし、大規模エンタープライズおよび ISV のお客様をサポートしています。データアーキテクトおよびソフトウェア開発エンジニアリングマネージャーとしての強固な経験を持つとともに、データ分析とデータサイエンスの分野で 16 年の経験を有しています。データアーキテクトとして、お客様のクラウドにおけるエンタープライズデータアーキテクチャソリューションの設計とスケーリングを支援してきました。エンジニアリングマネージャーとしては、エンジニアリングとプロダクトの双方の観点から新機能の提供と製品革新を推進し、QuickSight を通じてお客様のデータの力を引き出すことを可能にしました。