파일로 Power BI 보고서 내보내기

exportToFile API를 사용하면 REST 호출을 통해 Power BI 보고서를 내보낼 수 있습니다. 지원되는 파일 형식은 다음과 같습니다.

• .pptx(PowerPoint)
• .pdf
• .png
  • .png로 내보내는 경우 여러 페이지가 포함된 보고서는 .zip 파일로 압축됩니다.
  • .zip에 포함된 각 파일은 보고서 페이지를 나타냅니다.
  • 페이지 이름은 페이지 가져오기 또는 그룹의 페이지 가져오기 API의 반환값과 동일합니다.

참고 항목

exportToFile API를 사용하여 파일로 Power BI 보고서를 내보내는 것은 PPU(사용자 단위 Premium)에서 지원되지 않습니다.

사용 예

내보내기 기능은 여러 가지 방법으로 사용할 수 있습니다. 몇 가지 예는 다음과 같습니다.

• 인쇄로 보내기 단추 - 애플리케이션에서 클릭하면 내보내기 작업을 트리거하는 단추를 만듭니다. 작업은 표시된 보고서를 .pdf 또는 .pptx로 내보낼 수 있습니다. 완료되면 사용자는 파일을 다운로드로 받을 수 있습니다. 책갈피를 사용하여 구성된 필터, 슬라이서 및 기타 설정을 포함하여 특정 상태에서 보고서를 내보낼 수 있습니다. API는 비동기이므로 파일을 사용할 수 있게 되는 데 다소 시간이 걸릴 수 있습니다.

• 메일 첨부 파일 - .pdf 보고서를 첨부하여 설정된 간격마다 자동화된 메일을 보냅니다. 이 시나리오는 주별 보고서를 임원에게 자동으로 전송하려는 경우에 유용할 수 있습니다. 자세한 내용은 Power Automate를 사용하여 Power BI 보고서 내보내기 및 이메일로 보내기를 참조하세요.

API 사용

라이선스 요구 사항

• 내보내는 보고서는 Premium, Embedded 또는 Fabric 용량으로 지원되는 작업 영역에 있어야 합니다.
• exportToFile API는 PPU(Premium Per User)에 대해 지원되지 않습니다.

관리자 설정

API를 사용하기 전에 다음 관리자 테넌트 설정이 사용하도록 설정되었는지 확인합니다.

• PowerPoint 프레젠테이션 또는 PDF 문서로 보고서 내보내기 - 기본적으로 사용하도록 설정됩니다.
• 이미지 파일로 보고서 내보내기 - .png에만 필요하며 기본적으로 사용되지 않습니다.

"렌더링" 이벤트

시각적 개체가 렌더링을 완료하기 전에 내보내기를 시작하지 않도록 하려면 “렌더링” 이벤트 API를 사용하고 렌더링이 완료된 경우에만 내보내기를 시작합니다.

폴링

이 API는 비동기식입니다. exportToFile API를 호출하면 내보내기 작업을 트리거합니다. 내보내기 작업을 트리거한 후 폴링을 사용하여 완료될 때까지 작업을 추적합니다.

폴링을 수행하는 동안 API는 완료된 작업량을 나타내는 숫자를 반환합니다. 각 내보내기 작업의 작업은 작업의 총 내보내기 수에 따라 계산됩니다. 내보내기에는 단일 시각적 개체 또는 책갈피가 있거나 없는 페이지 내보내기가 포함됩니다. 모든 내보내기는 가중치가 같습니다. 예를 들어 내보내기 작업에 10페이지가 포함된 보고서 내보내기가 포함되고 폴링이 70을 반환하는 경우 API가 내보내기 작업의 10개 페이지 중 7개를 처리했음을 의미합니다.

내보내기가 완료되면 폴링 API 호출이 파일을 가져오기 위한 Power BI URL을 반환합니다. URL은 24시간 동안 사용할 수 있습니다.

지원되는 기능

이 섹션에서는 지원되는 다음 기능을 사용하는 방법을 설명합니다.

• 인쇄할 페이지 선택
• 페이지 또는 단일 시각적 개체 내보내기
• 책갈피
• 필터
• 인증
• 행 수준 보안(RLS)
• 데이터 보호
• 지역화
• 동적 바인딩

인쇄할 페이지 선택

페이지 가져오기 또는 그룹의 페이지 가져오기 반환 값에 따라 인쇄할 페이지를 지정합니다. 내보낼 페이지의 순서를 지정할 수도 있습니다.

페이지 또는 단일 시각적 개체 내보내기

페이지나 단일 시각적 개체를 지정하여 내보낼 수 있습니다. 페이지를 책갈피와 함께 또는 책갈피 없이 내보낼 수 있습니다.

내보내기 유형에 따라 ExportReportPage 개체에 다른 특성을 전달해야 합니다. 다음 표에서는 각 내보내기 작업에 필요한 특성을 지정합니다.

참고 항목

단일 시각적 개체 내보내기는 페이지 내보내기(책갈피 포함 여부와 관계없음)와 가중치가 동일합니다. 즉, 시스템 계산 측면에서 두 작업은 동일한 값을 전달합니다.

Attribute	페이지	단일 시각적 개체	설명
bookmark	선택 사항		페이지를 특정 상태로 내보내는 데 사용합니다.
pageName			GetPages REST API 또는 getPages 클라이언트 API를 사용합니다.
visualName			시각적 개체의 이름을 가져오는 방법은 두 가지입니다. getVisuals 클라이언트 API를 사용합니다. 시각적 개체를 선택할 때 트리거되는 visualClicked 이벤트를 수신 대기하고 기록합니다. 자세한 내용은 How to handle events(이벤트를 처리하는 방법)를 참조하세요. .

책갈피

책갈피는 적용된 필터 및 보고서 시각적 개체의 상태를 포함하여 특정 구성으로 보고서를 저장하는 데 사용할 수 있습니다. exportToFile API를 사용하여 다음과 같은 두 가지 방법으로 보고서의 책갈피를 프로그래밍 방식으로 내보낼 수 있습니다.

• 기존 책갈피 내보내기

  기존 보고서 책갈피를 내보내려면 책갈피 JavaScript API를 사용하여 가져올 수 있는 고유한(대/소문자 구분) 식별자인 name 속성을 사용합니다.

• 보고서의 상태 내보내기

  보고서의 현재 상태를 내보내려면 state 속성을 사용합니다. 예를 들어 책갈피의 bookmarksManager.capture 메서드를 사용하여 특정 사용자가 보고서에 대해 만든 변경 내용을 캡처한 다음, capturedBookmark.state를 사용하여 현재 상태로 내보낼 수 있습니다.

참고 항목

개인 책갈피 및 영구 필터는 지원되지 않습니다.

필터

PowerBIReportExportConfiguration에서 reportLevelFilters를 사용하면 필터링된 조건으로 보고서를 내보낼 수 있습니다.

필터링된 보고서를 내보내려면 필터로 사용할 URL 쿼리 문자열 매개 변수를 ExportFilter에 삽입합니다. 문자열을 입력할 때 URL 쿼리 매개 변수의 ?filter= 부분을 제거해야 합니다.

테이블에는 전달할 ExportFilter수 있는 문자열의 몇 가지 구문 예제가 포함되어 있습니다.

Filter	구문	예시
필드의 값 하나	Table/Field eq 'value'	Store/Territory eq 'NC'
필드의 여러 값	Table/Field in ('value1', 'value2')	Store/Territory in ('NC', 'TN')
한 필드의 고유 값 하나와 다른 필드의 다른 고유 값 하나	Table/Field1 eq 'value1' 및 Table/Field2 eq 'value2'	Store/Territory eq 'NC' 및 Store/Chain eq 'Fashions Direct'

인증

사용자(또는 마스터 사용자) 또는 서비스 주체를 사용하여 인증할 수 있습니다.

행 수준 보안(RLS)

RLS(행 수준 보안)를 사용하여 특정 사용자 에게만 표시되는 데이터를 포함하는 보고서를 내보낼 수 있습니다. 예를 들어 지역 역할로 정의된 판매 보고서를 내보내는 경우 특정 지역만 표시되도록 보고서를 프로그래밍 방식으로 필터링할 수 있습니다.

RLS를 사용하여 내보내려면 다음과 같은 권한이 있어야 합니다.

• 보고서가 연결된 의미 체계 모델에 대한 쓰기 및 다시 공유 권한
• 보고서가 있는 작업 영역의 작업 영역 구성원 또는 관리자

데이터 보호

.pdf 및 .pptx 형식은 민감도 레이블을 지원합니다. 민감도 레이블이 있는 보고서를 .pdf 또는 .pptx로 내보내면 내보낸 파일에 민감도 레이블이 있는 보고서가 표시됩니다.

민감도 레이블이 포함된 보고서는 서비스 주체를 사용하여 .pdf 또는 .pptx로 내보낼 수 없습니다.

지역화

exportToFile API를 사용하는 경우 원하는 로캘을 전달할 수 있습니다. 지역화 설정은 보고서가 표시되는 방식에 영향을 줍니다(예: 선택한 로컬에 따라 서식 변경).

동적 바인딩

기본 의미 체계 모델이 아닌 다른 의미 체계 모델에 연결된 상태에서 보고서를 내보내려면 API를 호출할 때 datasetToBind 매개 변수에 필요한 의미 체계 모델 ID를 지정합니다. 동적 바인딩에 대해 자세히 알아보세요.

동시 요청

exportToFile API는 제한된 수의 동시 요청을 지원합니다. 지원되는 최대 동시 요청 수는 용량당 500개입니다. 한도를 초과하지 않고 너무 많은 요청(429) 오류가 발생하지 않도록 하려면 시간 경과에 따라 또는 용량 전체에서 부하를 분산합니다. 보고서의 5개 페이지만 동시에 처리됩니다. 예를 들어 50페이지가 포함된 보고서를 내보내는 경우 내보내기 작업은 10개의 순차적 간격으로 처리됩니다. 내보내기 작업을 최적화할 때 몇 가지 작업을 병렬로 실행하는 것이 좋습니다.

코드 예제

내보내기 작업을 만들 때 다음 네 단계를 수행해야 합니다.

1. 내보내기 요청 보내기
2. 폴링
3. 파일 가져오기
4. 파일 스트림 사용

이 섹션에서는 각 단계에 대한 예제를 제공합니다.

1단계 - 내보내기 요청 보내기

첫 번째 단계는 내보내기 요청을 보내는 것입니다. 이 예제에서는 특정 페이지에 대한 내보내기 요청을 보냅니다.

private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId,
    FileFormat format,
    IList<string> pageNames = null, /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
    var powerBIReportExportConfiguration = new PowerBIReportExportConfiguration
    {
        Settings = new ExportReportSettings
        {
            Locale = "en-us",
        },
        // Note that page names differ from the page display names
        // To get the page names use the GetPages REST API
        Pages = pageNames?.Select(pn => new ExportReportPage(Name = pn)).ToList(),
        // ReportLevelFilters collection needs to be instantiated explicitly
        ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

    };

    var exportRequest = new ExportReportRequest
    {
        Format = format,
        PowerBIReportConfiguration = powerBIReportExportConfiguration,
    };

    // The 'Client' object is an instance of the Power BI .NET SDK
    var export = await Client.Reports.ExportToFileInGroupAsync(groupId, reportId, exportRequest);

    // Save the export ID, you'll need it for polling and getting the exported file
    return export.Id;
}

2단계 - 폴링

내보내기 요청을 보낸 후 폴링을 사용하여 대기 중인 내보내기 파일이 준비된 시기를 식별합니다.

private async Task<HttpOperationResponse<Export>> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the PostExportRequest response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    HttpOperationResponse<Export> httpMessage = null;
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int c_secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations 
            return null;
        }

        // The 'Client' object is an instance of the Power BI .NET SDK
        httpMessage = await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
        exportStatus = httpMessage.Body;

        // You can track the export progress using the PercentComplete that's part of the response
        SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(), exportStatus.PercentComplete);
        if (exportStatus.Status == ExportState.Running || exportStatus.Status == ExportState.NotStarted)
        {
            // The recommended waiting time between polling requests can be found in the RetryAfter header
            // Note that this header is not always populated
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;
            await Task.Delay(retryAfterInSec * c_secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return httpMessage;
}

3단계 - 파일 가져오기

폴링이 URL을 반환하면 이 예제를 사용하여 받은 파일을 가져옵니다.

private async Task<ExportedFile> GetExportedFile(
    Guid reportId,
    Guid groupId,
    Export export /* Get from the PollExportRequest response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        // The 'Client' object is an instance of the Power BI .NET SDK
        var fileStream = await Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
        return new ExportedFile
        {
            FileStream = fileStream,
            FileSuffix = export.ResourceFileExtension,
        };
    }
    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string FileSuffix;
}

4단계 - 파일 스트림 사용

파일 스트림이 있는 경우 가장 적합한 방식으로 파일 스트림을 처리할 수 있습니다. 예를 들어 파일 스트림을 메일로 보내거나 내보낸 보고서를 다운로드하는 데 사용할 수 있습니다.

엔드투엔드 예제

보고서를 내보내는 엔드투엔드 예제입니다. 이 예제는 다음과 같은 단계로 구성됩니다.

1. 내보내기 요청 보내기
2. 폴링
3. 파일 가져오기

private async Task<ExportedFile> ExportPowerBIReport(
	Guid reportId,
	Guid groupId,
	FileFormat format,
	int pollingtimeOutInMinutes,
	CancellationToken token,
	IList<string> pageNames = null,  /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
	const int c_maxNumberOfRetries = 3; /* Can be set to any desired number */
	const int c_secToMillisec = 1000;
	try
	{
		Export export = null;
		int retryAttempt = 1;
		do
		{
			var exportId = await PostExportRequest(reportId, groupId, format, pageNames, urlFilter);
			var httpMessage = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
			export = httpMessage.Body;
			if (export == null)
			{
				// Error, failure in exporting the report
				return null;
			}
			if (export.Status == ExportState.Failed)
			{
				// Some failure cases indicate that the system is currently busy. The entire export operation can be retried after a certain delay
				// In such cases the recommended waiting time before retrying the entire export operation can be found in the RetryAfter header
				var retryAfter = httpMessage.Response.Headers.RetryAfter;
				if(retryAfter == null)
				{
				    // Failed state with no RetryAfter header indicates that the export failed permanently
				    return null;
                }

                var retryAfterInSec = retryAfter.Delta.Value.Seconds;
                await Task.Delay(retryAfterInSec * c_secToMillisec);
            }
        }
        while (export.Status != ExportState.Succeeded && retryAttempt++ < c_maxNumberOfRetries);

        if (export.Status != ExportState.Succeeded)
        {
            // Error, failure in exporting the report
            return null;
        }

        var exportedFile = await GetExportedFile(reportId, groupId, export);

        // Now you have the exported file stream ready to be used according to your specific needs
        // For example, saving the file can be done as follows:
        /*
            var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;

            using (var fileStream = File.Create(pathOnDisk))
            {
                exportedFile.FileStream.CopyTo(fileStream);
            }
        */

        return exportedFile;
    }
    catch
    {
        // Error handling
        throw;
    }
}

고려 사항 및 제한 사항

• 내보내기 API 작업 부하는 프리미엄 용량 부하 평가에 설명된 대로 느리게 실행되는 백그라운드 작업으로 평가됩니다.
• 내보내는 보고서의 모든 관련 의미 체계 모델은 직접 쿼리 연결이 있는 의미 체계 모델을 포함하여 Premium 또는 Embedded 용량에 있어야 합니다.
• 내보낸 보고서는 250MB의 파일 크기를 초과할 수 없습니다.
• .png로 내보내는 경우에는 민감도 레이블이 지원되지 않습니다.
• 내보낸 단일 보고서에 포함할 수 있는 내보내기 수(단일 시각적 개체 또는 보고서 페이지)는 50개입니다(페이지를 매긴 보고서 내보내기는 포함되지 않음). 요청에 더 많은 내보내기가 포함된 경우 API는 오류를 반환하고 내보내기 작업은 취소됩니다.
• 개인 책갈피와 영구 필터는 Power BI 보고서 파일로 내보내기에 지원되지 않습니다.
• API는 exportToFile 책갈피 또는 reportLevelFilters 없이 사용하는 경우 기본값으로 보고서를 내보냅니다.
• 여기에 나열된 Power BI 시각적 개체는 지원되지 않습니다. 이러한 시각적 개체가 포함된 보고서를 내보낼 때 이러한 시각적 개체가 포함된 보고서 부분은 렌더링되지 않고 오류 기호를 표시합니다.
  • 인증되지 않은 Power BI 사용자 지정 시각적 개체
  • R 시각적 개체
  • PowerApps
  • Python 시각적 개체
  • Power Automate
  • 페이지를 매긴 보고서의 시각적 개체
  • Visio
  • ArcGIS 시각적 개체

관련 콘텐츠

고객 및 조직용 콘텐츠를 포함하는 방법을 검토합니다.

• 페이지를 매긴 보고서를 파일로 내보내기
• 고객에 대한 콘텐츠 포함
• 조직에 포함
• Power Automate를 사용하여 Power BI 보고서 내보내기 및 이메일로 보내기

궁금한 점이 더 있나요? Power BI 커뮤니티를 이용하세요.