기존 앱 재사용
마지막 업데이트: 2026. 10. 14.QV2QS는 배포할 때마다 새 앱을 생성하는 대신 기존 Qlik Sense 앱을 대상으로 지정할 수 있어, 반복적인 개발이 가능하고 앱 ID를 유지할 수 있습니다.
기본적으로 QV2QS는 배포할 때마다 새 앱을 생성합니다.대신 기존 앱을 대상으로 지정하여 앱을 제자리에서 업데이트하고 앱 ID를 유지하세요.이 접근 방식을 사용하면 반복적인 개발이 가능하며 특정 앱 ID를 참조하는 북마크 및 링크를 유지할 수 있습니다.
재사용을 뒷받침하는 세 가지 논거:
--appId APP_ID— 앱 ID를 직접 지정합니다.--appIdFile PATH— 텍스트 파일의 첫 번째 줄에서 앱 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를 참조하는 북마크, 즐겨찾기 및 직접 링크를 보존합니다.
매핑은 두 위치에 저장됩니다:
- 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 파일의 전체 경로를 기록합니다.이후 실행 시 QV2QS는 여러 폴더가 동일한 기본 이름을 공유하는 경우에도(예: Sales/, Sales_2/, Sales_3/) 마커를 사용하여 지정된 QVW 파일의 올바른 프로젝트 폴더를 찾습니다.
마커는 각 QVW 파일이 정확히 하나의 출력 폴더에 매핑되도록 보장합니다.이전에 변환된 QVW 파일을 변환할 때, QV2QS는 출력 루트에서 마커가 소스 경로와 일치하는 하위 폴더를 검색합니다.일치하는 항목이 발견되면 QV2QS는 해당 폴더를 재사용하고 그 안의 cloud_state.json을(를) 읽습니다.일치하는 항목이 없는 경우, QV2QS는 숫자 접미사가 붙은 새 하위 폴더를 생성합니다.
마법사에서도 동일한 매칭 로직이 적용됩니다.기존 앱 재사용이 활성화되어 있으면 마법사는 출력 폴더에서 일치하는 프로젝트를 확인하고 이전 배포에서 AppId 필드를 자동으로 채웁니다.이전 배포를 찾을 수 없는 경우 해당 필드는 비어 있는 상태로 유지되며, 직접 입력하거나 찾아보기 선택기를 사용할 수 있습니다.
.qv2qs_source 마커 파일이 자동으로 생성됩니다.파일을 편집하거나 삭제하지 마십시오.마커를 제거하면 QV2QS는 다음 실행 시 기존 하위 폴더를 재사용하는 대신 새 프로젝트 하위 폴더를 생성합니다.
재배포 동작
QV2QS는 qlik app build을(를) 사용하여 대상 앱에 배포합니다.빌드 명령은 앱 개체 모델의 전체 교체를 수행합니다.빌드 출력에 정의된 모든 개체는 앱에 기록됩니다.빌드 출력에 없는 개체는 제거됩니다.
빌드를 실행하기 전에 QV2QS는 교체를 위해 기존 시트를 준비합니다.QV2QS는 라이브 앱을 기준으로 시트 매핑의 유효성을 검사하고(시트 ID 매핑 참조), 각 시트의 게시 상태와 순위를 기록하며, 클라우드 앱에서 기존 시트를 제거합니다.해당 ID를 참조하는 북마크와 링크가 빌드 후에도 계속 작동할 수 있도록 로컬 빌드 출력은 원본 Qlik Sense 시트 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이(가) 필요합니다.--reload와 결합하여 UI를 업데이트한 후 기존 스크립트를 실행할 수 있으며, 이는 대상 앱에 이미 작동하는 Qlik Cloud 데이터 연결이 있는 경우 유용합니다.또한 --autoBinary와(과) 결합하여 대상 스크립트를 그대로 유지하면서 원본 QVW 파일에서 데이터를 임시로 로드할 수도 있습니다.
대상 앱 변수 보존
기본적으로 QV2QS는 대상 앱의 변수를 QlikView 소스에서 변환된 변수로 대체합니다.대상 앱의 기존 변수를 변경하지 않고 유지하려면 --preserveTargetAppVariables을(를) 사용하십시오.변환된 변수는 로컬 variables.json 파일에 기록되지만 클라우드 앱에는 적용되지 않습니다.
이 옵션은 기존 앱을 대상으로 할 때만 적용되므로 --appId 또는 --reuseAppId이(가) 필요합니다.--preserveTargetAppScript와 결합하여 대상 앱의 로드 스크립트와 변수를 모두 그대로 유지할 수 있습니다.