보고서 설정 구성

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

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

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

다음 섹션에서는 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 속성이 지원하는 값을 확인할 수 있습니다.

속성	표시	Expanded
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

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

작업 모음

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

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

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

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

참고

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

보기 모드의 작업 표시줄의 경우 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"
        }
    }
};

참고

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

투명한 배경

기본적으로 포함된 콘텐츠의 배경은 회색 여백이 있는 흰색입니다. 원하는 경우 포함된 콘텐츠에 투명한 배경을 제공할 수 있습니다. 그런 다음 포함된 콘텐츠가 포함된 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
    }
};

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

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

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

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

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

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

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

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

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 보고서의 필터를 동적으로 변경하는 방법을 제공합니다. 단계적 포함 중에 이 메서드를 사용하는 경우 보고서가 처음 적용되는 필터를 재정의할 수 있습니다. 필터를 생성하고 메서드를 사용하는 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 획득한 포함 토큰에 충분한 권한이 있는 경우에만 작동합니다. 포함 토큰에 대한 자세한 내용은 포함 토큰 만들기를 참조하세요.

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

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

콘텐츠가 편집 모드에 있고 보기 모드로 전환하려는 경우 다음 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");

고려 사항 및 제한 사항

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

• 작업 표시줄이 표시되면 페이지 탐색 위치를 변경할 수 없습니다. 작업 표시줄에 대해 자세히 알아봅니다.

• 막대에 bars 설명된 대로 속성에서 setting 속성을 사용하는 경우 포함된 콘텐츠가 편집 모드인 경우에만 API가 구성을 적용합니다. 콘텐츠가 보기 모드인 경우 API는 설정을 무시합니다 bars .

• 사용 하는 경우는 viewMode 편집 모드에서 콘텐츠를 표시 하는 속성, 두 가지 추가 단계를 수행 해야 합니다.

  • 속성을 사용하여 사용 권한 수준을 구성합니다 permissions . 해당 권한 수준은 사용자에게 콘텐츠를 수정하기 위한 적절한 액세스 권한을 부여해야 합니다. instance 경우 사용자의 값을 Read, 할당 permissions 하면 콘텐츠를 편집할 수 없습니다.
  • 생성하는 포함 토큰에 편집을 지원하는 권한이 있는지 확인합니다. instance 경우 API 값 view, 이 있는 토큰을 accessLevel 획득하면 편집 모드에서 콘텐츠를 표시하지 못합니다.

• panes 속성은 다음 settings 속성을 대체합니다.

  • filterPaneEnabled
  • navContentPaneEnabled

  속성을 사용하여 panes 필터 또는 페이지 탐색 표시 유형을 구성하는 경우 앱에서 또는 navContentPaneEnabled 속성을 사용하지 filterPaneEnabled 마세요.

• API는 테마와 대비 수준을 포함된 콘텐츠에 동시에 적용할 수 없습니다. 및 속성을 사용하여 theme 두 옵션을 모두 구성하는 경우 API는 포함된 콘텐츠와 함께 값을 contrastMode 사용합니다.contrastMode 그러나 API는 설정을 무시합니다 theme .

• 포함된 보고서에 책갈피를 적용하려는 경우 속성을 사용할 bookmark 수 있습니다. 해당 속성과 함께 책갈피 이름을 제공하는 경우 API는 해당 이름을 가진 책갈피가 있는 경우에만 책갈피를 사용할 수 있습니다. 마찬가지로 속성을 사용하여 pageName 여는 페이지를 지정하는 경우 API는 지정된 이름의 페이지가 있는 경우에만 해당 페이지를 표시할 수 있습니다. 이름을 구성하기 전에 Report getPages 메서드와 같은 접근자 메서드를 사용하여 해당 이름의 구성 요소가 있는지 여부를 검사 것이 좋습니다.

다음 단계

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