다음을 통해 공유

책갈피를 사용하여 사용자 환경 향상

  • 아티클

Power BI의 보고서 책갈피를 사용하면 모든 필터 및 시각적 개체의 상태를 포함하여 포함된 보고서 페이지의 현재 상태를 캡처할 수 있습니다. 나중에 보고서를 열 때 책갈피를 선택하여 보고서를 저장된 상태로 복원할 수 있습니다. 개발자는 Power BI 클라이언트 API를 사용하여 책갈피를 캡처하고 적용하여 사용자 환경을 제어할 수 있습니다.

저장된 책갈피는 보고서의 일부로 저장된 책갈피이거나 보고서의 실시간 상태로 캡처된 책갈피일 수 있습니다. 보고서를 로드할 때 저장된 책갈피를 적용하는 경우 책갈피의 이름 또는 상태를 제공하여 사용할 책갈피를 지정할 수 있습니다. 이름으로 책갈피를 제공하는 경우 보고서에 동일한 이름의 저장된 책갈피가 포함되어야 합니다.

이 문서에서는 책갈피를 지원하는 보고서를 포함해야 하는 다양한 API 설정을 설명합니다.

메모

조직대한 포함하는 보고서에서 보고서 소비자는 보고서 상태를 캡처하고 책갈피를 선택하여 해당 상태로 신속하게 돌아가서 개인 책갈피를 만듭니다. 자세한 내용은 개인 책갈피 참조하세요.

고객을 위해 포함하는 보고서에서 유사한 환경을 만드는 방법에 대한 자세한 내용은 Power BI 임베디드 분석 놀이터에서 캡처 보고서 보기 쇼케이스 참조하세요.

Power BI에서 책갈피를 사용하는 방법에 대한 자세한 내용은 Power BI Desktop책갈피 만들기를 참조하세요.

Power BI를 포함할 때 개인 책갈피를 사용하는 방법에 대한 자세한 내용은 개인 책갈피참조하세요.

보고서 책갈피를 사용하는 방법

다음 섹션에서는 Power BI 클라이언트 API를 사용하여 보고서 책갈피를 사용하는 방법을 보여 줍니다.

보고서의 책갈피 관리

보고서의 책갈피를 관리하려면 포함된 보고서 인스턴스bookmarksManager 속성을 사용합니다.

BookmarksManager 클래스에는 다음 메서드가 있습니다.

  • getBookmarks - 보고서와 연결된 저장된 책갈피 목록을 반환합니다.

  • apply - 보고서에 이전에 저장된 책갈피의 이름으로 적용됩니다.

  • capture - 보고서의 현재 상태를 나타내는 base64 serialization 문자열을 캡처하고 반환합니다.

  • applyState 보고서에 책갈피의 이전에 캡처한 base64 serialization 상태를 적용합니다.

  • play - 보고서의 책갈피에 대한 슬라이드 쇼 프레젠테이션 모드를 제어합니다.

보고서 책갈피 액세스

개별 책갈피에 액세스하려면 getBookmarks 메서드를 사용하여 ReportBookmark 개체 목록에 액세스합니다. ReportBookmark 클래스에는 다음과 같은 속성이 있습니다.

  • name - 보고서 책갈피의 고유 식별자입니다.

  • displayName - 책갈피 창에 표시되는 보고서 책갈피의 표시 이름입니다.

  • state - 보고서 책갈피 상태의 base64 serialization입니다. 이 메서드를 저장하고 bookmarksManager.applyState 메서드를 사용하여 보고서에 적용할 수 있습니다.

  • children - 보고서 책갈피 그룹이 있는 경우 보고서 책갈피 그룹을 나타내는 ReportBookmark 개체 목록입니다.

보고서 책갈피 API 사용

포함된 보고서에서 개발자는 다음을 수행할 수 있습니다.

저장된 보고서 책갈피 목록 가져오기

보고서와 연결된 저장된 책갈피 목록을 얻으려면 보고서의 bookmarksManager 속성에서 반환된 BookmarksManager 개체의 getBookmarks 메서드를 호출합니다.

getBookmarks 메서드는 다음과 같이 정의됩니다.

getBookmarks(): Promise<models.IReportBookmark[]>

예를 들어:

let bookmarks = await report.bookmarksManager.getBookmarks();

보고서 로드 또는 세션 중에 이름으로 저장된 책갈피 적용

책갈피 이름을 사용하여 이전에 저장된 책갈피를 보고서에 적용하려면 보고서의 bookmarksManager 속성에서 반환된 BookmarksManager 개체의 apply 메서드를 호출합니다.

자세한 내용은 보고서 설정 구성참조하세요.

apply 메서드는 다음과 같이 정의됩니다.

apply(bookmarkName: string): Promise<void>

예를 들어:

await report.bookmarksManager.apply("Bookmark1234");

책갈피 개체로 현재 보기 캡처 및 가져오기

보고서의 현재 상태를 base64 문자열로 캡처하려면 BookmarksManager 개체의 capture 메서드를 호출합니다. capture 메서드는 특정 보고서에 저장되지 않은 책갈피를 나타내는 IReportBookmark 개체를 반환합니다. IReportBookmark.state 속성을 사용하여 책갈피 상태를 식별하는 base64 문자열을 반환합니다. 이 문자열은 나중에 로드 시간 또는 런타임 동안 보고서에 적용할 수 있습니다.

capture 메서드는 다음과 같이 정의됩니다.

capture(options?:ICaptureBookmarkOptions): Promise<models.IReportBookmark>

예를 들어:

let capturedBookmark = await report.bookmarksManager.capture();

책갈피 옵션 캡처

ICaptureBookmarkOptions 개체를 capture 메서드에 전달할 수도 있습니다.

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages - 기본적으로 캡처된 책갈피 상태는 현재 페이지 상태만 저장합니다. 모든 페이지의 상태를 캡처하려면 allPages 옵션을 true설정하여 capture 메서드를 호출합니다.
  • personalizeVisuals - 개인 설정된 시각적 개체사용하여 현재 상태를 캡처하려면 personalizeVisuals 옵션을 true설정하여 capture 메서드를 호출합니다.

예를 들어 다음 코드는 개인 설정된 시각적 개체를 포함하여 모든 페이지의 상태를 캡처합니다.

let capturedBookmark = await report.bookmarksManager.capture({
    allPages: true,
    personalizeVisuals: true
});

보고서 로드 또는 세션 중에 캡처된 책갈피 상태 적용

이전에 캡처한 책갈피 상태를 보고서에 적용하려면 BookmarksManager 개체의 applyState 메서드를 사용합니다.

자세한 내용은 보고서 설정 구성참조하세요.

applyState 메서드는 다음과 같이 정의됩니다.

applyState(state: string): Promise<void>

예를 들어:

await report.bookmarksManager.applyState(capturedBookmark.state);

보고서 책갈피가 적용될 때 추가 논리 수행

보고서 책갈피가 적용된 시기를 확인하려면 보고서 개체의 on 메서드를 호출하여 bookmarkApplied 이벤트를 수신 대기합니다.

예를 들어:

report.on("bookmarkApplied", (event) => {
    console.log(event.detail.name);
});

책갈피 창 표시 또는 숨기기

Power BI 책갈피 창을 표시하거나 숨기려면 보고서 설정의 panes 속성을 업데이트합니다.

책갈피 창 표시

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: true
        }
    }
};

책갈피 창 숨기기

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: false
        }
    }
};

보고서 설정 업데이트에 대한 자세한 내용은 보고서 설정 구성을 참조하세요.

책갈피 슬라이드 쇼 모드 입력 또는 종료

보고서의 책갈피에 대한 슬라이드 쇼 프레젠테이션 모드를 제어하려면 BookmarksManager 개체의 play 메서드를 호출합니다. 자세한 내용은 책갈피를 슬라이드 쇼참조하세요.

play 메서드는 다음과 같이 정의됩니다.

play(playMode: models.BookmarksPlayMode): Promise<void>

메모

책갈피 슬라이드 쇼 모드를 입력하기 전에 getBookmarks API보고서에 책갈피가 하나 이상 있는지 확인합니다.

슬라이드 쇼 프레젠테이션 모드 입력

await report.bookmarksManager.play(models.BookmarksPlayMode.Presentation);

슬라이드 쇼 프레젠테이션 모드 종료

await report.bookmarksManager.play(models.BookmarksPlayMode.Off);

고려 사항 및 제한 사항

  • 책갈피 API를 사용하는 경우 보고서에 대한 특정 변경 내용으로 인해 오류 또는 예기치 않은 결과가 발생할 수 있습니다. 이 예제 중 하나는 보고서에서 보고서 필터를 제거하는 것입니다. 오류를 방지하려면 해당 필터 카드가 있어야 합니다. 필터를 제거하는 대신 해당 값을 All설정합니다. 삭제되거나 변경된 필터를 모르는 경우 보고서에 변경 내용을 적용한 후 책갈피를 다시 캡처합니다.

  • embed 세션에서 만들거나 업데이트 필터에 의해 추가된 부하 필터의 같은 필터는작업을 추가하지만 책갈피 상태로 캡처되지만 현재 세션에서만 적용됩니다. 이 제한을 해결하려면 필터를 보고서에 All 값으로 저장하고 업데이트 필터 업데이트 작업사용하여 포함 세션에서 수정해야 합니다.

관련 콘텐츠