Power BI Desktop 프로젝트 보고서 폴더

아티클
08/13/2024

Important

Power BI Desktop 프로젝트는 현재 미리 보기에 있습니다.

이 문서에서는 Microsoft Power BI Desktop 프로젝트의 보고서 폴더에 있는 파일 및 하위 폴더에 대해 설명합니다. 여기에 있는 파일 및 하위 폴더는 Power BI 보고서를 나타냅니다. 프로젝트에 따라 보고서 폴더에는 다음이 포함될 수 있습니다.

.pbi\
- localSettings.json
CustomVisuals\
StaticResources\
- RegisteredResources\
semanticModelDiagramLayout.json
definition.pbir¹
mobileState.json
report.json²
definition\ 폴더³
.platform

1 - 이 파일이 필요합니다.
2 - 이 파일은 PBIR-레거시 형식으로 저장할 때 필요합니다.
3 - 이 파일은 PBIR 형식으로 저장할 때 필요합니다.

모든 프로젝트 보고서 폴더에 여기에 설명된 모든 파일 및 하위 폴더가 포함되지는 않습니다.

보고서 파일

.pbi\localSettings.json

현재 사용자 및 로컬 컴퓨터에만 적용되는 보고서 설정을 포함합니다. gitIgnore 또는 기타 소스 제어 제외에 포함되어야 합니다. 기본적으로 Git은 이 파일을 무시합니다.

자세한 내용은 localSettings.json 스키마 문서를 참조하세요.

CustomVisuals\

보고서의 사용자 지정 시각적 개체에 대한 메타데이터를 포함하는 하위 폴더입니다. Power BI는 세 가지 종류의 사용자 지정 시각적 개체를 지원합니다.

조직 저장소 시각적 개체 - 조직에서는 조직의 Power BI에 사용자 지정 시각적 개체를 승인하고 배포할 수 있습니다. 자세한 내용은 조직 저장소를 참조하세요.
AppSource Power BI 시각적 개체 - "퍼블릭 사용자 지정 시각적 개체"라고도 합니다. 이러한 시각적 개체는 Microsoft AppSource에서 사용할 수 있습니다. 보고서 개발자는 Power BI Desktop에서 직접 이러한 시각적 개체를 설치할 수 있습니다.
사용자 지정 시각적 개체 파일 - "프라이빗 사용자 지정 시각적 개체"라고도 합니다. pbiviz 패키지를 업로드하여 파일을 보고서에 로드할 수 있습니다.

프라이빗 사용자 지정 시각적 개체만 CustomVisuals 폴더에 로드됩니다. AppSource 및 조직 시각적 개체는 Power BI Desktop에서 자동으로 로드합니다.

RegisteredResources\

사용자 지정 테마, 이미지 및 사용자 지정 시각적 개체(pbiviz 파일)와 같이 보고서에 특정하고 사용자가 로드한 리소스 파일을 포함하는 하위 폴더입니다.

개발자는 여기에서 파일을 담당하며 변경 내용이 지원됩니다. 예를 들어 파일을 변경할 수 있으며 Power BI Desktop을 다시 시작하면 새 파일이 보고서에 로드됩니다. 이 폴더는 다음과 같은 몇 가지 유용한 시나리오의 차단을 해제할 수 있습니다.

공용 스키마를 사용하여 Power BI Desktop 외부에서 사용자 지정 테마를 작성합니다.
여러 보고서에서 리소스 파일을 변경하여 일괄 처리 변경 내용을 적용합니다. 예를 들어 회사 사용자 지정 테마를 전환하고, 밝은 테마와 어두운 테마 간에 변경하고, 로고 이미지를 변경할 수 있습니다.

모든 리소스 파일에는 report.json 파일에 해당 항목이 있어야 합니다. 이 항목은 미리 보기 동안에는 편집을 지원하지 않습니다. RegisteredResources 파일에 대한 편집은 Power BI Desktop에서 report.json에 리소스를 등록하게 하는 이미 로드된 리소스에 대해서만 지원됩니다.

semanticModelDiagramLayout.json

보고서와 관련된 의미 체계 모델의 구조를 설명하는 데이터 모델 다이어그램이 포함되어 있습니다. 미리 보기 동안 이 파일은 외부 편집을 지원하지 않습니다.

definition.pbir

보고서 및 핵심 설정의 전체 정의를 포함합니다. 이 파일에는 보고서에서 사용되는 의미 체계 모델에 대한 참조도 포함되어 있습니다. Power BI Desktop은 pbip 파일에서 보고서를 연 것과 동일하게 pbir 파일을 직접 열 수 있습니다. pbir을 열면 byPath를 사용하는 상대 참조가 있는 경우 의미 체계 모델도 함께 열립니다.

예제 definition.pbir:

{
  "version": "1.0",
  "datasetReference": {
    "byPath": {
      "path": "../Sales.Dataset"
    },
    "byConnection": null
  }
}

정의에는 보고서에 사용된 의미 체계 모델을 참조하는 datasetReference 속성이 포함되어 있습니다. 참조는 다음 중 하나일 수 있습니다.

byPath - 대상 의미 체계 모델 폴더에 대한 상대 경로를 지정합니다. 절대 경로는 지원되지 않습니다. 슬래시(/)는 폴더 구분 기호로 사용됩니다. 사용하는 경우 Power BI Desktop은 전체 편집 모드에서 의미 체계 모델도 엽니다.

byConnection - 연결 문자열을 사용하여 Power BI 서비스에서 원격 의미 체계 모델을 지정합니다. byConnection 참조가 사용되면 Power BI Desktop은 편집 모드에서 의미 체계 모델을 열지 않습니다.

byConnection 참조를 사용하여 다음 속성을 지정해야 합니다.

속성	설명
connectionString	원격 의미 체계 모델을 참조하는 연결 문자열.
pbiModelDatabaseName	원격 의미 체계 모델 ID.
connectionType	연결의 유형입니다. 서비스 원격 의미 체계 모델의 경우 이 값은 `pbiServiceXmlaStyleLive`여야 합니다.
pbiModelVirtualServerName	`sobe_wowvirtualserver` 값이 있어야 하는 내부 속성입니다.

byConnection을(를) 사용하는 예제:

{
  "version": "1.0",
  "datasetReference": {
    "byPath": null,
    "byConnection": {
      "connectionString": "Data Source=powerbi://api.powerbi.com/v1.0/myorg/WorkpaceName;Initial Catalog=SemanticModelName;Integrated Security=ClaimsToken",
      "pbiServiceModelId": null,
      "pbiModelVirtualServerName": "sobe_wowvirtualserver",
      "pbiModelDatabaseName": "e244efd3-e253-4390-be28-6be45d9da47e",
      "connectionType": "pbiServiceXmlaStyleLive",
      "name": null
    }
  }
}

의미 체계 모델과 보고서가 동일한 작업 영역을 공유하는 경우 Fabric Git 통합은 항상 의미 체계 모델에 대한 byPath 참조를 사용합니다.

또한 이 파일은 'version' 속성을 통해 지원되는 보고서 정의 형식을 지정합니다.

버전	지원되는 형식
1.0	보고서 정의는 report.json 파일에 PBIR-Legacy로 저장되어야 합니다.
4.0 이상	보고서 정의는 PBIR-Legacy(report.json 파일) 또는 PBIR(\definition 폴더)로 저장할 수 있습니다.

자세한 내용은 definition.pbir 스키마 문서를 참조하세요.

mobileState.json

모바일 장치에서 렌더링할 때 보고서 모양 및 동작 설정을 포함합니다. 이 파일은 외부 편집을 지원하지 않습니다.

report.json

이 파일에는 Power BI 보고서 레거시 형식(PBIR-Legacy)의 보고서 정의가 포함되어 있으며 외부 편집을 지원하지 않습니다.

definition\ 폴더

이 폴더는 Power BI 프로젝트가 Power BI 향상된 보고서 형식(PBIR)을 사용하여 저장된 경우에만 사용할 수 있습니다. 이는 report.json 파일을 바꿉니다.

좋습니다.

Fabric 항목과 Git 간의 연결을 설정하고 유지하는 데 필수적인 속성을 보유하는 Fabric 플랫폼 파일입니다.

자세한 내용은 Git 통합 자동 생성 시스템 파일을 참조하세요.

PBIR 형식

Important

미리 보기 단계에서는 모든 PBIR 제한 사항을 고려하세요.

Power BI PBIR(Enhanced Report Format)을 사용하여 Power BI 프로젝트 파일(PBIP)을 저장하면 올바른 형식의 JSON 파일을 사용하여 변경 내용 추적 및 병합 충돌 해결이 크게 개선됩니다.

친숙한 PBIR 차이 비교의 스크린샷.

각 페이지, 시각적 개체, 책갈피 등은 폴더 구조 내에서 별도의 개별 파일로 구성됩니다. 이 형식은 공동 개발 충돌 해결에 이상적입니다.

친숙한 PBIR 폴더의 스크린샷.

PBIR-Legacy(report.json)와 달리 PBIR은 Power BI가 아닌 애플리케이션의 수정을 지원하는 공개적으로 문서화된 형식입니다. 각 파일에는 파일을 문서화할 뿐만 아니라 Visual Studio Code와 같은 코드 편집기가 편집하는 동안 구문 유효성 검사를 수행할 수 있도록 하는 공용 JSON 스키마가 있습니다.

현재 PBIR에서 사용할 수 있는 몇 가지 시나리오는 다음과 같습니다.

보고서 간에 페이지/시각적/책갈피를 복사합니다.
시각적 파일을 복사하고 붙여넣어 모든 페이지에서 시각적 개체 집합의 일관성을 보장합니다.
여러 보고서 파일을 쉽게 찾고 바꿀 수 있습니다.
스크립트를 사용하여 모든 시각적 개체에 일괄 처리 편집 적용(예: 시각적 수준 필터 숨기기)

PBIR 형식 미리 보기 기능 사용

PBIR을 사용하여 Power BI 프로젝트로 저장하는 것은 현재 미리 보기 상태입니다. 사용하기 전에 Power BI Desktop 미리 보기 기능에서 사용하도록 설정합니다.

파일 > 옵션 및 설정 > 옵션 > 미리 보기 기능으로 이동하여 향상된 메타데이터 서식(PBIR)을 사용하여 보고서 저장 옆의 확인란을 선택합니다.

PBIR을 사용하여 프로젝트로 저장

PBIR 미리 보기 기능을 사용하도록 설정하면 프로젝트를 저장할 때 보고서가 보고서 폴더 내 \definition 폴더에 저장됩니다.

보고서 pbip 폴더 내의 정의 폴더 스크린샷.

PBIR 폴더 구조에 대해 자세히 알아봅니다.

기존 PBIP를 PBIR로 변환

PBIR-레거시 형식을 사용하는 PBIP가 이미 있는 경우 다음과 같이 PBIR로 변환할 수 있습니다.

Power BI Desktop에서 PBIP를 엽니다.
미리 보기 기능이 사용하도록 설정되어 있는지 확인합니다.
프로젝트를 저장합니다. PBIR로 업그레이드할지 묻는 메시지가 나타납니다.
업그레이드를 선택합니다.

Important

PBIR로 업그레이드한 후에는 PBIR-Legacy로 되돌릴 수 없습니다. PBIR-Legacy로 되돌리려고 한다면 먼저 PBIP 파일의 복사본을 저장합니다.

레거시 PBIR-레거시 파일(report.json)은 보고서의 PBIR 표현이 포함된 \definition 폴더로 바뀝니다.

현재 형식 유지를 선택하면 데스크톱에서 업그레이드하라는 메시지를 다시 표시하지 않습니다.

서비스에 PBIR 보고서 게시

미리 보기 단계에서 PBIR 형식으로 보고서를 게시하는 유일한 방법은 Fabric Git 통합을 이용하는 것입니다. 여기에는 작업 영역을 Git 리포지토리에 연결하고 PBIR 보고서를 여기에 푸시하는 작업이 포함되며, 이후 단계에서 서비스 작업 영역과 동기화될 수 있습니다.

서비스에서 기존 보고서를 PBIR로 변환하려면 다음 단계를 따릅니다.

작업 영역을 Git에 연결합니다.
Git 리포지토리를 로컬 파일 시스템에 복제합니다.
definition.pbir 파일을 열어 Power BI Desktop에서 보고서를 엽니다.
보고서를 저장하고 PBIR로 업그레이드하도록 선택합니다.
변경 내용을 Git에 커밋하고 동기화합니다.
Git의 최신 변경 내용으로 작업 영역을 업데이트합니다.

PBIR 폴더 및 파일

보고서 정의는 다음 구조로 definition\ 폴더 내에 저장됩니다.

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json

파일/폴더	Required	설명
bookmarks\	아니요	보고서의 모든 책갈피 파일을 보관하는 폴더입니다.
── [bookmarkName].bookmark.json	아니요	대상 시각적 개체 및 필터와 같은 책갈피 메타데이터입니다. 자세한 내용은 스키마를 참조하세요.
── bookmarks.json	아니요	책갈피 순서 및 그룹과 같은 책갈피 메타데이터입니다. 자세한 내용은 스키마를 참조하세요.
pages\	예	보고서의 모든 페이지를 보관하는 폴더입니다.
── [pageName]\	예	페이지당 하나의 폴더입니다.
──── visuals\	아니요	페이지의 모든 시각적 개체를 보관하는 폴더입니다.
────── [visualName]\	아니요	시각적 개체당 하나의 폴더입니다.
──────── mobile.json	아니요	모바일 위치 및 서식과 같은 시각적 모바일 레이아웃 메타데이터입니다. 자세한 내용은 스키마를 참조하세요.
──────── visual.json	예	위치, 서식 등의 시각적 메타데이터를 쿼리합니다. 자세한 내용은 스키마를 참조하세요.
──── page.json	예	페이지 수준 필터 및 서식과 같은 페이지 메타데이터입니다. 자세한 내용은 스키마를 참조하세요.
── pages.json	아니요	페이지 순서 및 활성 페이지와 같은 페이지 메타데이터입니다. 자세한 내용은 스키마를 참조하세요.
version.json	예	PBIR 파일 버전은 무엇보다도 로드에 필요한 파일을 결정합니다. 자세한 내용은 스키마를 참조하세요.
reportExtensions.json	아니요	보고서 수준 측정값과 같은 보고서 확장입니다. 자세한 내용은 스키마를 참조하세요.
report.json	예	보고서 수준 필터 및 서식과 같은 보고서 메타데이터입니다. 자세한 내용은 스키마를 참조하세요.

PBIR 명명 규칙

앞의 표에서 대괄호([]) 안의 모든 식별 이름은 기본 명명 규칙을 따르지만 보다 사용자에게 식별 이름으로 바꿀 수 있습니다. 기본적으로 페이지, 시각적 개체 및 책갈피는 보고서 개체 이름을 파일 또는 폴더 이름으로 사용합니다. 이러한 개체 이름은 처음에 '90c2e07d8e84e7d5c026'과 같은 20자의 고유 식별자입니다.

PBIR 이름 속성의 스크린샷.

각 JSON 파일 내에서 '이름' 속성 이름을 바꾸는 것은 지원되지만 보고서 내부와 외부 모두에서 외부 참조가 손상될 수 있습니다. 개체 이름 및/또는 파일/폴더 이름은 하나 이상의 단어 문자(문자, 숫자, 밑줄) 또는 하이픈으로 구성되어야 합니다.

PBIR 파일 또는 폴더의 이름을 바꾼 후에는 Power BI Desktop을 다시 시작해야 합니다. 다시 시작하면 Power BI Desktop은 저장할 때 원본 파일 또는 폴더 이름을 유지합니다.

PBIR Json 스키마

각 PBIR JSON 파일에는 문서 상단에 JSON 스키마 선언이 포함되어 있습니다. 이 스키마 URL은 공개적으로 액세스할 수 있으며 각 파일에 사용 가능한 속성 및 개체에 대해 자세히 알아보는 데 사용할 수 있습니다. 또한 Visual Studio Code와 같은 코드 편집기로 편집할 때 기본 제공된 IntelliSense 및 유효성 검사 기능을 제공합니다.

프롬프트 PBIR JSON 스키마 도구 설명의 스크린샷.

스키마 URL은 보고서 정의가 발전함에 따라 변경될 것으로 예상되는 문서 버전도 정의합니다.

모든 JSON 스키마는 여기에 게시되어 있습니다.

PBIR 주석

각 visual, page 및 report에 대한 보고서 정의 내에 주석을 이름 값 쌍으로 포함할 수 있습니다. Power BI Desktop은 이러한 주석을 무시하지만 스크립트와 같은 외부 애플리케이션에 유용할 수 있습니다.

예를 들어, report.json 파일에서 보고서에 대한 defaultPage를 지정할 수 있으며, 그러면 배포 스크립트에서 이를 활용할 수 있습니다.

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/report/1.0.0/schema.json",
  "themeCollection": {
    "baseTheme": {
      "name": "CY24SU06",
      "reportVersionAtImport": "5.55",
      "type": "SharedResources"
    }
  },
  ...
  "annotations": [
    {
      "name": "defaultPage",
      "value": "c2d9b4b1487b2eb30e98"
    }
  ]
}

PBIR 파일의 외부 변경 내용

파일이 JSON 스키마를 준수하는 한 Visual Studio Code와 같은 코드 편집기나 외부 도구를 사용하여 PBIR JSON 파일을 편집할 수 있습니다. 잘못된 속성 이름이나 형식을 사용하면 Visual Studio Code에서 직접 쉽게 검색할 수 있습니다.

프롬프트 PBIR JSON 스키마 유효성 검사 스크린샷.

PBIR 콘텐츠에 대한 외부 변경으로 인해 Power BI Desktop에서 파일을 다시 열 때 오류가 발생할 수 있습니다. 이러한 오류는 두 가지 형식이 될 수 있습니다.

차단 오류로 인해 Power BI Desktop이 보고서를 열 수 없습니다. 이러한 오류는 다시 열기 전에 수정해야 하는 문제와 잘못된 파일을 식별하는 데 도움이 됩니다.

프롬프트 PBIR 차단 오류의 스크린샷.

잘못된 스키마 또는 필수 속성 누락과 같은 오류는 차단 오류로 간주됩니다. 이러한 오류는 Visual Studio Code에서 파일을 열고 스키마 오류를 검사하여 쉽게 식별할 수 있습니다.

비차단 오류는 Power BI Desktop이 보고서를 여는 것을 방해하지 않으며 자동으로 해결됩니다.

프롬프트 PBIR 비차단 오류의 스크린샷.

잘못된 activePageName 구성과 같은 오류는 자동으로 수정되는 비차단 오류의 예입니다. 경고는 잠재적인 작업 손실을 방지하여 자동 수정으로 보고서를 저장하지 않을 수 있는 기회를 제공하는 데 필요합니다.

일반적인 PBIR 오류

시나리오: 시각적 개체 또는 페이지 폴더 이름을 바꾼 후 보고서를 열 때 내 시각적 개체 또는 페이지가 더 이상 표시되지 않습니다.

솔루션: 이름이 명명 규칙을 준수하는지 확인합니다. 그렇지 않은 경우 Power BI Desktop은 파일 또는 폴더를 무시하고 프라이빗 사용자 파일로 처리합니다.

시나리오: 새 보고서 개체의 이름이 다른 보고서 개체 이름과 다르게 지정됩니다. 예를 들어, 대부분의 페이지 폴더 이름은 'ReportSection0e71dafbc949c0853608'이고 일부 폴더 이름은 '1b3c2ab12b603618070b'입니다.

솔루션: PBIR은 모든 개체에 대해 새로운 명명 규칙을 채택했지만 이는 새 개체에만 적용됩니다. 기존 보고서를 PBIP로 저장할 때 참조가 끊어지는 것을 방지하기 위해 현재 이름을 보존해야 합니다. 일관성을 원한다면 스크립트 일괄 이름 바꾸기가 허용됩니다.

시나리오: 책갈피 파일을 복사했는데 저장하자마자 책갈피 구성의 대부분이 삭제되었습니다.

솔루션: 이 동작은 의도적이며, 보고서 책갈피는 모든 시각적 개체와 함께 보고서 페이지의 상태를 캡처합니다. 캡처된 상태는 시각적 개체가 다른 보고서 페이지에서 발생하므로 잘못된 시각적 개체는 책갈피 구성에서 제거됩니다. 종속 시각적 개체 및 페이지도 복사하는 경우 책갈피는 해당 구성을 유지합니다.

시나리오: 다른 보고서에서 페이지 폴더를 복사했는데 "'pageBinding.name' 속성 값은 고유해야 합니다."라는 오류가 발생했습니다.

솔루션: 드릴스루 및 페이지 도구 설명을 지원하려면 pageBinding 개체가 필요합니다. 다른 페이지에서 참조될 수 있으므로 이름은 보고서 내에서 고유해야 합니다. 새로 복사한 페이지에서 고유한 값을 할당하여 오류를 해결합니다. 2024년 6월 이후에는 pageBinding 이름이 기본적으로 GUID이므로 이 상황은 더 이상 문제가 되지 않습니다.

PBIR 고려 사항 및 제한 사항

PBIR은 현재 미리 보기 상태입니다. 다음 사항을 고려하세요.

서비스 제한 사항
- 모바일 보기는 Power BI Apps에 표시되지 않습니다.
- 배포 파이프라인을 사용하여 배포할 수 없습니다.
- 복사본으로 저장할 수 없습니다.
500개가 넘는 파일이 포함된 대규모 보고서에서는 다음을 포함한 작성 성능 문제가 발생합니다(보고서 보기는 영향을 받지 않음).
- Power BI Desktop에 저장
- Fabric Git 통합의 동기화
보고서가 PBIR-Legacy에서 PBIR로 변환되면 롤백할 수 없습니다.
"다른 이름으로 저장" 기능을 사용하여 PBIP 파일을 PBIX 파일로 변환하면 PBIX 파일 내에 PBIR 보고서가 포함되어 모든 PBIR 제한 사항이 PBIX에 전달됩니다.

서비스에 의해 적용되는 PBIR 크기 제한 사항:

보고서당 최대 1,000페이지.
페이지당 최대 시각적 개체 수는 300개입니다.
각 책갈피 파일당 최대 5MB.
각 파일당 최대 1MB입니다.
보고서당 최대 리소스 패키지 파일은 1,000개입니다.
모든 리소스 패키지 파일의 최대 크기는 300MB입니다.
모든 보고서 파일의 최대 크기는 20MB입니다.

공개 미리 보기 중에 Fabric Git 통합 및 Fabric REST API는 보고서 정의를 내보낼 때 PBIR-Legacy(report.json)를 계속 사용합니다. 그러나 PBIR 형식을 사용하여 보고서를 Fabric으로 가져오는 경우 두 기능 모두 PBIR 형식을 사용하여 보고서 정의 내보내기를 시작합니다.

다음을 통해 공유

Power BI Desktop 프로젝트 보고서 폴더

보고서 파일

.pbi\localSettings.json

CustomVisuals\

RegisteredResources\

semanticModelDiagramLayout.json

definition.pbir

mobileState.json

report.json

definition\ 폴더

좋습니다.

PBIR 형식

PBIR 형식 미리 보기 기능 사용

PBIR을 사용하여 프로젝트로 저장

기존 PBIP를 PBIR로 변환

서비스에 PBIR 보고서 게시

PBIR 폴더 및 파일

PBIR 명명 규칙

PBIR Json 스키마

PBIR 주석

PBIR 파일의 외부 변경 내용

일반적인 PBIR 오류

PBIR 고려 사항 및 제한 사항

피드백

추가 리소스

다음을 통해 공유

Power BI Desktop 프로젝트 보고서 폴더

보고서 파일

.pbi\localSettings.json

CustomVisuals\

RegisteredResources\

semanticModelDiagramLayout.json

definition.pbir

mobileState.json

report.json

definition\ 폴더

좋습니다.

PBIR 형식

PBIR 형식 미리 보기 기능 사용

PBIR을 사용하여 프로젝트로 저장

기존 PBIP를 PBIR로 변환

서비스에 PBIR 보고서 게시

PBIR 폴더 및 파일

PBIR 명명 규칙

PBIR Json 스키마

PBIR 주석

PBIR 파일의 외부 변경 내용

일반적인 PBIR 오류

PBIR 고려 사항 및 제한 사항

관련 콘텐츠

피드백

추가 리소스