보고서 설정 구성

아티클
07/17/2024

Power BI 클라이언트 API를 사용하여 애플리케이션에 Power BI 분석을 포함할 수 있습니다. 이 클라이언트 쪽 라이브러리를 사용하여 Power BI 보고서를 포함하는 경우 API에 해당 보고서에 대한 정보를 제공합니다.

구성 개체를 사용하여 Power BI 보고서에 대한 정보를 저장할 수 있습니다. 보고서를 포함하면 해당 개체를 API에 전달합니다.

보고서에 대한 API 액세스 권한을 제공하는 것 외에도 구성 개체를 사용하여 보고서의 모양과 동작을 사용자 지정할 수 있습니다. 예를 들어 구성 개체에서 필터 표시 유형, 탐색 액세스 및 위치 설정을 조정할 수 있습니다.

다음 섹션에서는 Power BI 콘텐츠를 포함하고 구성하는 방법을 설명합니다.

구성 정보 제공

IReportLoadConfiguration 인터페이스는 구성 개체가 보고서에 대해 Power BI 클라이언트 API에 제공할 수 있는 속성을 표시합니다.

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

이 인터페이스의 필수 매개 변수에 대한 설명과 보고서를 포함하는 방법을 보여 주는 코드 예제는 보고서 포함하는 참조하세요.

설정 사용자 지정

다음 섹션에서는 settings 속성을 사용하여 포함된 Power BI 보고서의 모양과 동작을 조정하는 방법을 설명합니다. 보고서가 이미 로드된 경우 보고서 설정을 업데이트하려면 report.updateSettings 메서드를 사용합니다. 자세한 내용은 런타임업데이트 보고서 설정을 참조하세요.

창

다음 코드와 같이 단일 panes 속성을 사용하여 Power BI 보고서의 모든 창 모양을 제어합니다.

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

다음 표에서 각 panes 속성이 지원하는 값을 확인할 수 있습니다.

재산	보이는	확장
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

필터 창

기본적으로 필터 창이 표시됩니다. 이 창을 숨기려면 다음 코드와 같이 filterPaneEnabled 속성을 사용합니다.

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

메모

창 속성filterPaneEnabled 속성을 대체합니다. 이전 버전과의 호환성을 유지하기 위해 filterPaneEnabled 속성이 여전히 존재합니다. 그러나 이러한 두 속성을 함께 사용하지 않아야 합니다.

기본적으로 페이지 탐색 화살표는 포함된 보고서에 표시됩니다. 이러한 화살표를 숨기려면 다음 코드와 같이 navContentPaneEnabled 속성을 사용합니다.

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

메모

창 속성navContentPaneEnabled 속성을 대체합니다. 이전 버전과의 호환성을 유지하기 위해 navContentPaneEnabled 속성이 여전히 존재합니다. 그러나 이러한 두 속성을 함께 사용하지 않아야 합니다.

새 세로 페이지 창을 사용하려면 보고서 아래쪽에 페이지 탐색 창이 나타나며 position 속성을 설정할 수 있습니다.

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

메모

updateSettings사용하여 페이지 탐색 창의 위치를 변경할 수 없습니다.

바

bars 속성을 사용하여 작업 표시줄 및 상태 표시줄의 표시 유형을 설정합니다.

작업 표시줄

다음 코드는 작업 표시줄을 표시합니다.

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

또는 보기 모드에서 actionBarEnabled URL 매개 변수를 사용할 수도 있습니다.

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

메모

보기 모드에서 작업 표시줄은 조직 시나리오에 대한 포함에 대해서만 지원됩니다.

보기 모드의 작업 표시줄에는 Azure AD 애플리케이션에 대한 UserState.ReadWrite.All 권한을 사용하도록 설정하는 것이 좋습니다. 이 권한은 최종 사용자가 즐겨찾기에 보고서를 추가할 수 있도록 허용하고 개인 책갈피를 사용하도록 설정하고 영구 필터를 데 필요합니다.

상태 표시줄

상태 표시줄에는 캔버스를 확대/축소하는 기능을 제공하는 캔버스 확대/축소 컨트롤러가 있습니다.

다음 코드는 상태 표시줄을 표시합니다.

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

로캘 설정

localeSettings 속성을 사용하여 포함된 보고서의 언어 및 서식을 지정합니다.

localeSettings language 속성은 각각 하이픈으로 구분된 두 문자로 구성됩니다.

언어 Power BI가 지역화에 사용하는 언어를 정의합니다. 언어의 예로는 en(영어), es(스페인어), tr(터키어)가 있습니다.
로캘 Power BI에서 날짜, 통화 및 기타 관련 콘텐츠에 사용하는 텍스트 서식을 정의합니다. 로캘의 예로는 미국(영어), ES(스페인), TR(Türkiye)가 있습니다.

사용 가능한 언어 및 지역 목록은 지원되는 언어 참조하세요.

다음 코드는 이러한 localeSettings특정 값을 할당합니다.

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

메모

보고서를 로드한 후에는 로캘 설정을 변경할 수 없습니다. 보고서 로캘 설정을 변경하려면 powerbi.reset(element)호출하여 iframe을 다시 설정한 다음 보고서를 다시 포함합니다.

투명한 배경

기본적으로 포함된 콘텐츠의 배경은 회색 여백이 있는 흰색입니다. 원하는 경우 포함된 콘텐츠에 투명한 배경을 제공할 수 있습니다. 그런 다음 포함된 콘텐츠가 포함된 HTML div 요소에 원하는 스타일을 적용할 수 있습니다. 그런 다음 div 요소의 스타일이 표시됩니다.

포함된 콘텐츠의 배경을 투명하게 만들려면 다음 코드를 사용합니다.

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

하이퍼링크 클릭 동작

테이블 또는 행렬 기본 시각적 개체에서 하이퍼링크의 동작을 제어할 수 있습니다. 기본적으로 하이퍼링크는 새 창을 엽니다.

사용 가능한 동작 모드:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate - URL이 새 검색 컨텍스트로 로드됩니다.
NavigateAndRaiseEvent - URL이 새 검색 컨텍스트에 로드되고 dataHyperlinkClicked 이벤트가 발생합니다.
RaiseEvent - URL 클릭의 기본 동작을 방지하고 dataHyperlinkClicked 이벤트를 발생합니다.

이벤트를 발생 하려면 링크의 동작을 변경 하려면이 코드를 사용 합니다.

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

기본 테이블 또는 행렬 시각적 개체에서 하이퍼링크를 클릭하고 동작이 NavigateAndRaiseEvent 또는 RaiseEvent때 dataHyperlinkClicked 이벤트가 발생합니다.

report.on('dataHyperlinkClicked', () => {
    ...
});

이벤트 처리에 대한 자세한 내용은 이벤트처리하는 방법을 참조하세요.

시각적으로 렌더링된 이벤트

렌더링된 각 시각적 개체에 대한 이벤트를 수신 대기할 수 있습니다. 기본적으로 시각적으로 렌더링된 이벤트는 사용하지 않도록 설정됩니다.

이 코드를 사용하여 visualRendered 이벤트를 트리거합니다.

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

시각적 개체가 렌더링되고 보고서 설정에서 visualRenderedEvents 사용하도록 설정되면 visualRendered 이벤트가 발생합니다.

report.on('visualRendered', () => {
    ...
});

이벤트 처리에 대한 자세한 내용은 이벤트처리하는 방법을 참조하세요.

메모

시각적 개체는 사용자 상호 작용으로 인해 렌더링될 수 있으므로 필요한 경우에만 이 이벤트를 켜는 것이 좋습니다.

오류 메시지

포함된 보고서에 사용자 지정된 오류 메시지를 표시하려면 hideErrors 속성을 사용하여 기본 Power BI 포함된 오류 메시지를 숨깁니다. 그러면 코드에서 앱 디자인에 맞는 방식으로 오류 이벤트를 처리할 수 있습니다. 기본 오류 재정의에 대한 자세한 내용은 기본 오류 메시지 재정의를 참조하세요.

기본 오류 메시지를 숨기려면 다음 코드를 사용합니다.

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

옵션 사용자 지정

다음 섹션에서는 더 많은 속성을 사용하여 포함된 Power BI 보고서의 모양과 동작을 추가로 사용자 지정하는 방법을 설명합니다.

기본 페이지

처음에 표시되는 포함된 보고서의 페이지를 제어할 수 있습니다. 기본적으로 초기 페이지는 가장 최근에 수정한 페이지로, 보고서를 마지막으로 저장했을 때 활성 페이지였습니다. pageName 속성을 사용하고 표시할 페이지의 이름으로 제공하여 이 동작을 재정의할 수 있습니다. 그러나 Power BI에 해당 이름의 페이지가 없으면 열기 요청이 실패합니다.

다음 코드는 특정 페이지를 표시하도록 앱을 구성하는 방법을 보여 줍니다.

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

부하 필터

포함된 보고서에 앱이 적용되는 필터를 제어할 수 있습니다. 기본적으로 보고서는 처음에 보고서에 저장한 필터를 사용합니다. 그러나 필터를 조정하려는 경우 두 가지 옵션이 있습니다.

저장된 필터와 함께 사용할 더 많은 필터를 구성합니다. 다음 코드에서는 filters 속성을 사용하여 더 많은 필터를 추가하는 방법을 보여 줍니다.
```
let embedConfig = {
    ...
    filters: [...]
};
```
저장된 필터를 새 집합으로 바꿉니다. setFilters 메서드는 보고서의 필터를 동적으로 변경하는 방법을 제공합니다. 단계적 포함 중에 이 메서드를 사용하는 경우 보고서가 처음 적용되는 필터를 재정의할 수 있습니다. 필터를 생성하고 메서드를 사용하는 방법에 대한 자세한 내용은컨트롤 보고서 필터를 참조하세요.

로드 슬라이서에서

포함된 보고서에 앱이 적용되는 슬라이서의 상태를 제어할 수 있습니다. 기본적으로 API는 보고서에 저장한 슬라이서를 사용합니다. 그러나 다음 코드와 같이 slicers 속성을 사용하여 기존 슬라이서의 상태를 수정할 수 있습니다.

embedConfig = {
    ...
    slicers: slicerArray,
};

슬라이서의 상태 수정에 대한 자세한 내용은 컨트롤 보고서 슬라이서 참조하세요.

로드 책갈피에서

bookmark 속성을 사용하여 포함된 보고서에 책갈피를 적용할 수 있습니다. 책갈피를 사용하여 현재 구성된 보고서 페이지 보기를 캡처하는 방법에 대한 자세한 내용은 책갈피 참조하세요.

책갈피 이름 또는 상태를 제공하여 사용할 책갈피를 지정할 수 있습니다. 책갈피 이름을 제공하는 경우 Power BI 보고서에는 해당 이름의 저장된 책갈피가 포함되어야 합니다.

bookmark 속성은 형식입니다IApplyBookmarkRequest. 다음 코드는 이 형식의 정의를 보여줍니다.

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

이 코드는 이름으로 책갈피를 지정하는 방법을 보여줍니다.

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

이 코드는 상태별로 책갈피를 지정하는 방법을 보여줍니다.

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

테마 및 고대비 모드

포함된 콘텐츠에서 사용하는 테마 및 대비 수준을 제어할 수 있습니다. 기본적으로 포함하는 모든 콘텐츠는 기본 테마와 대비가 0으로 표시됩니다. 특정 테마 또는 대비 수준을 구성하여 이 동작을 재정의할 수 있습니다. 테마에 대한 자세한 내용은 보고서 테마 적용참조하세요.

사용 가능한 대비 모드:

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

특정 테마를 구성하려면 다음 줄과 유사한 코드를 사용합니다.

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

다음 코드는 기본 대비 수준을 재정의하는 방법을 보여 None.

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

메모

API는 동시에 테마와 대비 수준을 적용할 수 없습니다. 두 속성을 모두 구성하는 경우 API는 지정한 대비 수준을 사용하지만 theme 설정을 무시합니다.

확대/축소 수준

보고서 확대/축소 수준 조정에 대한 자세한 내용은 접근성 문서확인하세요.

편집 모드에서 열기

기본적으로 포함하는 보고서는 보기 모드로 표시됩니다. 그러나 이 동작을 재정의하여 편집 모드에서 보고서를 열 수 있습니다. 모드 간에 전환할 수도 있습니다.

편집 모드 구성

편집 모드에서 포함된 보고서를 열려면 permissions 속성과 함께 viewMode 속성을 사용합니다.

viewMode 속성에 다음 값을 할당할 수 있습니다.

View - 보고서를 보기 모드로 엽니다.
Edit - 편집 모드에서 보고서를 엽니다.

다음 값을 permissions 속성을 할당할 수 있습니다.

Read - 사용자가 보고서를 볼 수 있습니다.
ReadWrite - 사용자가 보고서를 보고 편집하고 저장할 수 있습니다.
Copy - 사용자가 다른 이름으로 저장사용하여 보고서의 복사본을 저장할 수 있습니다.
Create - 사용자가 새 보고서를 만들 수 있습니다.
All - 사용자는 보고서의 복사본을 만들고, 보고, 편집하고, 저장하고, 저장할 수 있습니다.

편집 모드에서 열려는 콘텐츠를 구성할 때 다음 코드와 같이 permissions 속성에 편집에 적합한 값을 할당합니다.

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

메모

구성한 permissions 값은 획득한 embed 토큰에 충분한 권한이 있는 경우에만 작동합니다. 포함 토큰에 대한 자세한 내용은 embed 토큰만들기를 참조하세요.

편집 모드와 보기 모드 간 전환

포함된 콘텐츠가 시작될 모드를 지정하는 것 외에도 편집 모드와 보기 모드 간에 동적으로 전환할 수 있습니다.

콘텐츠가 편집 모드에 있고 보기 모드로 전환하려는 경우 다음 JavaScript 코드를 사용합니다.

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

콘텐츠가 보기 모드에 있고 편집 모드로 전환하려는 경우 다음 JavaScript 코드를 사용합니다.

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

고려 사항 및 제한 사항

포함된 콘텐츠를 구성할 때 다음 사항을 고려합니다.

작업 모음이 표시되면 페이지 탐색 위치를 변경할 수 없습니다. 작업 표시줄대해 자세히 알아봅니다.
막대설명된 대로 setting 속성에서 bars 속성을 사용하는 경우 포함된 콘텐츠가 편집 모드인 경우에만 API가 구성을 적용합니다. 콘텐츠가 보기 모드인 경우 API는 bars 설정을 무시합니다.
viewMode 속성을 사용하여 편집 모드에서 콘텐츠를 표시하는 경우 다음 두 단계를 추가로 수행해야 합니다.
- permissions 속성을 사용하여 사용 권한 수준을 구성합니다. 해당 권한 수준은 사용자에게 콘텐츠를 수정하기 위한 적절한 액세스 권한을 부여해야 합니다. 예를 들어 Read,permissions 값을 할당하면 사용자가 콘텐츠를 편집할 수 없습니다.
- 생성하는 포함 토큰에 편집을 지원하는 권한이 있는지 확인합니다. 예를 들어 accessLevel 값이 view, 토큰을 획득하면 API가 편집 모드에서 콘텐츠를 표시하지 못합니다.
창 속성 다음 settings 속성을 대체합니다.
- filterPaneEnabled
- navContentPaneEnabled
panes 속성을 사용하여 필터 또는 페이지 탐색 표시 유형을 구성하는 경우 앱에서 filterPaneEnabled 또는 navContentPaneEnabled 속성을 사용하지 마세요.
API는 포함된 콘텐츠에 테마와 대비 수준을 동시에 적용할 수 없습니다. theme 및 contrastMode 속성을 사용하여 두 옵션을 모두 구성하는 경우 API는 포함된 콘텐츠와 함께 contrastMode 값을 사용합니다. 그러나 API는 theme 설정을 무시합니다.
포함된 보고서에 책갈피를 적용하려면 bookmark 속성을 사용할 수 있습니다. 해당 속성에 책갈피 이름을 제공하는 경우 API는 해당 이름을 가진 책갈피가 있는 경우에만 책갈피를 사용할 수 있습니다. 마찬가지로 pageName 속성을 사용하여 여는 페이지를 지정하는 경우 API는 지정된 이름의 페이지가 있는 경우에만 해당 페이지를 표시할 수 있습니다. 이름을 구성하기 전에 Report getPages 메서드같은 접근자 메서드를 사용하여 구성 요소가 해당 이름으로 존재하는지 확인하는 것이 좋습니다.

책갈피 사용하여 사용자 환경 개선
Power BI 보고서 테마 적용
컨트롤 보고서 필터
보고서 슬라이서 제어

다음을 통해 공유

보고서 설정 구성

구성 정보 제공

설정 사용자 지정

창

필터 창

페이지 탐색 창

바

작업 표시줄

상태 표시줄

로캘 설정

투명한 배경

하이퍼링크 클릭 동작

시각적으로 렌더링된 이벤트

오류 메시지

옵션 사용자 지정

기본 페이지

부하 필터

로드 슬라이서에서

로드 책갈피에서

테마 및 고대비 모드

확대/축소 수준

편집 모드에서 열기

편집 모드 구성

편집 모드와 보기 모드 간 전환

고려 사항 및 제한 사항

추가 리소스

다음을 통해 공유

보고서 설정 구성

구성 정보 제공

설정 사용자 지정

창

필터 창

페이지 탐색 창

바

작업 표시줄

상태 표시줄

로캘 설정

투명한 배경

하이퍼링크 클릭 동작

시각적으로 렌더링된 이벤트

오류 메시지

옵션 사용자 지정

기본 페이지

부하 필터

로드 슬라이서에서

로드 책갈피에서

테마 및 고대비 모드

확대/축소 수준

편집 모드에서 열기

편집 모드 구성

편집 모드와 보기 모드 간 전환

고려 사항 및 제한 사항

관련 콘텐츠

추가 리소스