既存のアプリの再利用
最終更新日時: 2026/10/14QV2QS は、展開ごとに新しいアプリを作成する代わりに既存の Qlik Sense アプリを対象に指定できるため、反復的な開発が可能になり、アプリ ID が保持されます。
デフォルトでは、QV2QS は展開ごとに新しいアプリを作成します。アプリをインプレースで更新してアプリ ID を保持するには、代わりに既存のアプリを対象にします。このアプローチにより、反復的な開発が可能になり、特定のアプリIDを参照するブックマークやリンクが維持されます。
再利用を支持する3つの論拠があります:
--appId APP_ID— アプリIDを直接指定します。--appIdFile PATH— テキストファイルの1行目からアプリIDを読み取ります。--reuseAppId— プロジェクトのサブフォルダー内のcloud/cloud_state.jsonからアプリ ID を読み取ります。このファイルは、各展開の後に自動的に書き込まれます。
cloud/cloud_state.json ファイルはプロジェクトのサブフォルダー（例: <outputDir>/Sales/cloud/cloud_state.json）に保存されます。このファイルには、アプリID、メディアハッシュ、シートIDマッピング、ソースファイルパス、およびタイムスタンプが記録されます。--reuseAppId フラグはこのファイルを自動的に読み取るため、以降の実行ではアプリ ID を手動で入力することなく同じアプリが更新されます。バッチモードでは、--reuseAppId はプロジェクトごとに動作します — 各プロジェクトは独自の出力サブフォルダーから cloud_state.json を読み取ります。
シートIDマッピング
各 QlikView ドキュメントは、Document\SH01、Document\SH02 などの内部名によってシートを識別します。Qlik Sense は、シートの識別に UUID を使用します。QV2QS がアプリを初めてデプロイするとき、変換された各シートは新しい UUID を受け取ります。QV2QS は、デプロイ間でも関係が保持されるよう、ターゲット アプリ内に QlikView シート名と Qlik Sense UUID のマッピングを保存します。
同じアプリへの次回以降のデプロイでは、QV2QS は保存されているマッピングを読み取り、対応する変換済みシートに元の Qlik Sense UUID を割り当てます。マッピングにより、アプリ内に複製シートが表示されるのを防ぎ、特定のシート ID を参照するブックマーク、お気に入り、およびダイレクト リンクを保持します。
マッピングは 2 つの場所に格納されます:
- Qlik Cloud アプリ内 — アプリ内の専用オブジェクトがマッピングを保持します。アプリが別のスペースに移動された場合、または QVF としてエクスポートされた場合、マッピングはアプリとともに移動します。
- ローカルプロジェクトフォルダー内 —
cloud/cloud_state.jsonファイルには、同じマッピングのコピーが含まれています。--reuseAppIdフラグは、このファイルからアプリ ID とマッピングを読み取ります。
QV2QS は、再デプロイの準備を行う際、（ローカルファイルではなく）クラウドアプリからマッピングを常に読み取ります。ローカルファイルは、--reuseAppId フラグがアプリ ID を特定するための便宜上のものです。
メディアハッシュの最適化
QV2QS は、すべてのメディア ファイル (シートの背景、オブジェクトの背景、ボタン画像) のハッシュを計算し、そのハッシュをシート マッピングとともに保存します。以降のデプロイでは、QV2QS は現在のハッシュを保存された値と比較します。メディアが変更されていない場合、アップロードステップは完全にスキップされます。
マッピング検証
シートの置換を準備する前に、QV2QS は保存されたマッピングをライブ アプリと照合して検証します。デプロイとデプロイの間に Qlik Cloud アプリからシートが手動で削除された場合、QV2QS はシートが存在しなくなったことを検出し、マッピングから古いエントリを削除して、次回のビルド時に対応する QlikView シートを新規として扱います。ビルドの完了後、更新されたマッピングがアプリに書き戻されます。
QlikView ソースで追加または削除されたシート
初回展開後に QlikView ソースにシートが追加されると、QV2QS はそのシートに新しい UUID を割り当て、マッピングにエントリを追加します。QlikView ソースからシートが削除されると、そのシートはビルド出力に含まれなくなり、ビルド中に Qlik Cloud アプリから削除されます。削除されたシートのマッピングエントリは引き継がれません。
プロジェクトフォルダーのマッチング
QV2QSは、初回変換後に各プロジェクトの出力フォルダーに.qv2qs_sourceマーカーファイルを書き込みます。マーカーは、ソース QVW ファイルのフルパスを記録します。次回以降の実行では、複数のフォルダーが同じベース名を共有している場合でも (例: Sales/、Sales_2/、Sales_3/)、QV2QS はマーカーを使用して特定の QVW ファイルに対応する正しいプロジェクト フォルダーを特定します。
マーカーにより、各QVWファイルが確実に1つの出力フォルダーのみにマッピングされます。以前に変換された QVW ファイルを変換する場合、QV2QS は出力ルート内でマーカーがソース パスと一致するサブフォルダーを検索します。一致するものが見つかった場合、QV2QS はそのフォルダーを再利用し、その中の cloud_state.json を読み込みます。一致するものが見つからない場合、QV2QS は数値サフィックスが付いた新しいサブフォルダーを作成します。
ウィザードでも、同じマッチングロジックが適用されます。既存のアプリを再利用が有効になっている場合、ウィザードは出力フォルダーで一致するプロジェクトを確認し、前回の展開から AppId フィールドに自動的に入力します。以前の展開が見つからない場合、フィールドは空のままとなり、手動入力または参照ピッカーを受け付けます。
.qv2qs_source マーカー ファイルは自動的に作成されます。ファイルを編集または削除しないでください。マーカーを削除すると、QV2QS は次回の実行時に既存のプロジェクト サブフォルダーを再利用せず、新しいプロジェクト サブフォルダーを作成します。
再デプロイの動作
QV2QSはqlik app buildを使用してターゲットアプリに展開します。ビルド コマンドは、アプリ オブジェクト モデルの完全な置き換えを実行します。ビルド出力で定義されたすべてのオブジェクトがアプリに書き込まれます。ビルド出力に存在しないオブジェクトは削除されます。
ビルドを実行する前に、QV2QS は既存のシートを置換用に準備します。QV2QS は、ライブ アプリに対してシート マッピングを検証し (シート ID マッピングを参照)、各シートの公開状態とランクを記録して、クラウド アプリから古いシートを削除します。ローカルのビルド出力には元の Qlik Sense シート ID でパッチが適用されるため、それらの ID を参照するブックマークやリンクはビルド後も引き続き機能します。
ビルドの完了後、QV2QS は元のシートの状態を復元します。以前公開されていたシートはベース シートとして再公開され、元のランク (表示順) が復元されます。シートの公開設定が有効になっている場合、前回の展開に存在しなかった新しいシートはベース シートとして公開されます。新規シートを非公開のままにする設定を無効にします。
ターゲット アプリ内のユーザー作成コンテンツ (手動で追加されたシート、ブックマーク、ストーリー、または前回の展開後に作成されたカスタム オブジェクト) は、再展開時に保持されません。qlik app build コマンドは、アプリのコンテンツをビルド出力で置き換えます。手動で調整を行った場合は、再デプロイする前にアプリをバックアップまたは公開してください。
展開前バックアップ
既存のアプリを再利用する場合、QV2QS はアプリを変更する前にデータなしの QVF バックアップを自動的にエクスポートします。バックアップではデータを含めずにアプリ構造 (シート、オブジェクト、ロード スクリプト、メタデータ) をキャプチャするため、エクスポートが高速で、ファイル サイズが小さくなります。
バックアップは、プロジェクト出力フォルダー内の cloud/backups/ に保存されます。各バックアップファイルには <AppName>_<shortId>_<timestamp>_nodata.qvf という名前が付けられます。例: Sales_a1b2c3d4_20260226-143025_nodata.qvf。
バックアップのエクスポートに失敗した場合（たとえば、ネットワークの中断や権限不足などによる場合）、QV2QS は警告をログに記録し、展開を続行します。この失敗によって変換がブロックされることはありません。
自動バックアップをスキップするには、コマンドラインで --noBackup を渡すか、ウィザードで 展開前のバックアップをスキップ を有効にします。バックアップのスキップは、バックアップが外部で管理されているCI/CDパイプラインにおいて有用です。
ターゲット アプリのロード スクリプトの保持
デフォルトでは、QV2QS はターゲット アプリのロード スクリプトを、QlikView ソースから変換されたロード スクリプトに置き換えます。ターゲット アプリの既存のロード スクリプトを変更せずに維持するには、--preserveTargetAppScript を使用します。変換されたロード スクリプトはローカルの build/script.qvs ファイルに書き込まれますが、クラウド アプリには適用されません。
このオプションは、既存のアプリを対象とする場合にのみ適用されるため、--appId または --reuseAppId が必要です。UI を更新した後に既存のスクリプトを実行するために --reload と組み合わせることができます。これは、ターゲット アプリに機能する Qlik Cloud データ接続がすでに存在する場合に役立ちます。また、--autoBinary と組み合わせることで、ターゲット スクリプトをそのまま維持しながら、元の QVW ファイルから一時的にデータを読み込むこともできます。
ターゲットアプリの変数を保持する
デフォルトでは、QV2QS はターゲット アプリの変数を QlikView ソースから変換された変数に置き換えます。ターゲットアプリ内の既存の変数を変更せずに保持するには、--preserveTargetAppVariables を使用します。変換された変数はローカルの variables.json ファイルに書き込まれますが、クラウドアプリには適用されません。
このオプションは、既存のアプリを対象とする場合にのみ適用されるため、--appId または --reuseAppId が必要です。--preserveTargetAppScript と組み合わせることで、ターゲット アプリのロード スクリプトと変数の両方をそのまま維持することができます。