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

  • 아티클

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 직렬화 상태를 보고서에 적용합니다.

  • 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();

책갈피 옵션 캡처

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

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

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

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

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

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

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

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

applyState(state: string): Promise<void>

예를 들면 다음과 같습니다.

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

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

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

예를 들면 다음과 같습니다.

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로 설정합니다. 삭제되거나 변경된 필터를 모르는 경우 보고서에 변경 내용을 적용한 후 책갈피를 다시 캡처합니다.

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

다음 단계