페이지를 매긴 보고서를 파일로 내보내기
exportToFile API를 사용하면 REST 호출을 통해 Power BI 페이지를 매긴 보고서를 내보낼 수 있습니다. 지원되는 파일 형식은 다음과 같습니다.
.pptx(PowerPoint)
.pdf(및 액세스 가능 PDF 또는 PDF/UA)
.xlsx(Excel)
.docx(Word)
.csv
.xml
.mhtml
이미지
이미지로 내보내는 경우OutputFormat형식 설정을 통해 이미지 형식을 설정합니다. 지원되는OutputFormat값은 다음과 같습니다.- .tiff(기본값)
- .bmp
- .emf
- .gif
- .jpeg
- .png
사용 예
내보내기 기능은 다양한 방법으로 사용할 수 있습니다. 몇 가지 예는 다음과 같습니다.
인쇄로 보내기 단추 - 애플리케이션에서 클릭하면 내보내기 작업을 트리거하는 단추를 만듭니다. 작업은 표시된 보고서를 .pdf 또는 .pptx로 내보낼 수 있습니다. 완료되면 사용자는 파일을 다운로드로 받을 수 있습니다. 보고서 매개 변수와 형식 설정을 사용하면 필터링된 데이터, 사용자 지정 페이지 크기 및 기타 형식 관련 설정을 포함하여 보고서를 특정 상태로 내보낼 수 있습니다. API는 비동기이므로 파일을 사용할 수 있게 되는 데 다소 시간이 걸릴 수 있습니다.
메일 첨부 파일 - .pdf 보고서를 첨부하여 설정된 간격마다 자동화된 메일을 보냅니다. 이 시나리오는 주별 보고서를 임원에게 자동으로 전송하려는 경우에 유용할 수 있습니다.
API 사용
라이선스 요구 사항
- 내보내는 보고서는 Premium, Embedded 또는 Fabric 용량으로 지원되는 작업 영역에 있어야 합니다.
exportToFileAPI는 PPU(Premium Per User)에서 제한된 지원을 제공합니다.
이벤트 렌더링
시각적 개체가 렌더링을 완료하기 전에 내보내기를 시작하지 않도록 하려면 “렌더링” 이벤트 API를 사용하고 렌더링이 완료된 경우에만 내보내기를 시작합니다.
폴링
이 API는 비동기식입니다. exportToFile API를 호출하면 내보내기 작업을 트리거합니다. 내보내기 작업을 트리거한 후 폴링을 사용하여 완료될 때까지 작업을 추적합니다.
내보내기가 완료되면 폴링 API 호출이 파일을 가져오기 위한 Power BI URL을 반환합니다. URL은 24시간 동안 사용할 수 있습니다.
지원되는 기능
형식 설정
각 파일 형식에 대해 다양한 형식 설정을 지정합니다. 지원되는 속성과 값은 페이지를 매긴 보고서 URL 매개 변수의 디바이스 정보 매개 변수와 같습니다.
다음은 두 가지 예입니다. 첫 번째는 보고서 페이지 크기를 사용하여 보고서의 처음 4페이지를 .pptx 파일로 내보내는 것입니다. 두 번째 예제는 보고서의 세 번째 페이지를 .jpeg 파일로 내보내는 것입니다.
처음 4개 페이지를 .pptx로 내보내기
{
"format": "PPTX",
"paginatedReportConfiguration":{
"formatSettings":{
"UseReportPageSize": "true",
"StartPage": "1",
"EndPage": "4"
}
}
}
세 번째 페이지를 .jpeg로 내보내기
{
"format": "IMAGE",
"paginatedReportConfiguration":{
"formatSettings":{
"OutputFormat": "JPEG",
"StartPage": "3",
"EndPage": "3"
}
}
}
보고서 매개 변수
exportToFile API를 사용하면 보고서 매개 변수 세트를 통해 프로그래밍 방식으로 보고서를 내보낼 수 있습니다. 이 작업은 보고서 매개 변수 기능을 사용하여 수행합니다.
다음은 보고서 매개 변수 값을 설정하는 예제입니다.
{
"format": "PDF",
"paginatedReportConfiguration":{
"parameterValues":[
{"name": "State", "value": "WA"},
{"name": "City", "value": "Seattle"},
{"name": "City", "value": "Bellevue"},
{"name": "City", "value": "Redmond"}
]
}
}
인증
사용자(또는 마스터 사용자) 또는 서비스 주체를 사용하여 인증할 수 있습니다.
행 수준 보안(RLS)
RLS(행 수준 보안)가 정의된 Power BI 의미 체계 모델을 데이터 원본으로 사용하는 경우 특정 사용자에게만 표시되는 데이터를 포함하는 보고서를 내보낼 수 있습니다. 예를 들어 지역 역할로 정의된 판매 보고서를 내보내는 경우 특정 지역만 표시되도록 보고서를 프로그래밍 방식으로 필터링할 수 있습니다.
RLS를 사용하여 내보내려면, 보고서에서 데이터 원본으로 사용하는 Power BI 의미 체계 모델에 대한 읽기 권한이 있어야 합니다.
다음은 RLS에 유효한 사용자 이름을 제공하는 예제입니다.
{
"format": "PDF",
"paginatedReportConfiguration":{
"identities": [
{"username": "john@contoso.com"}
]
}
}
Single Sign-On SQL 및 Dataverse(SSO)
Power BI에는 SSO로 OAuth를 설정하는 옵션이 있습니다. 그러면 보고서를 보는 사용자의 자격 증명이 데이터를 검색하는 데 사용됩니다. 요청 헤더의 액세스 토큰은 데이터에 액세스하는 데 사용되지 않습니다. 토큰은 게시 본문에서 유효한 ID로 전달되어야 합니다.
액세스하려는 리소스에 대한 올바른 액세스 토큰을 가져오는 것은 때때로 까다로울 수 있습니다.
- Azure SQL의 경우 리소스는
https://database.windows.net입니다. - Dataverse의 경우 리소스는 사용자 환경의
https://주소입니다. 예:https://contoso.crm.dynamics.com.
AuthenticationContext. AcquireTokenAsync 메서드를 사용하여 토큰 API에 액세스합니다.
다음은 유효한 ID(사용자 이름)에 액세스 토큰을 제공하는 예제입니다.
{
"format":"PDF",
"paginatedReportConfiguration":{
"formatSettings":{
"AccessiblePDF":"true",
"PageHeight":"11in",
"PageWidth":"8.5in",
"MarginBottom":"2in"
},
"identities":[
{
"username":"john@contoso.com",
"identityBlob": {
"value": "eyJ0eX....full access token"
}
}
]
}
}
동시 요청
exportToFile은(는) 제한된 수의 동시 요청을 지원합니다. 동시 페이지를 매긴 보고서 렌더링 요청의 최대 수는 500개입니다. 한도를 초과하지 않고 너무 많은 요청(429) 오류가 발생하지 않도록 하려면 시간 경과에 따라 또는 용량 전체에서 부하를 분산합니다.
PPU(Premium Per User)를 사용하는 경우 exportToFile API는 5분 동안 하나의 요청만 허용합니다. 5분 내에 여러 요청이 제공되면 요청이 너무 많음(429) 오류가 발생합니다.
코드 예제
코드 예제에 사용된 Power BI API SDK는 여기에서 다운로드할 수 있습니다.
내보내기 작업을 만들 때 다음 세 단계를 수행해야 합니다.
- 내보내기 요청 보내기
- 폴링
- 파일 가져오기
이 섹션에서는 각 단계에 대한 예제를 제공합니다.
1단계 - 내보내기 요청 보내기
첫 번째 단계는 내보내기 요청을 보내는 것입니다. 이 예제에서는 특정 페이지 범위, 크기 및 보고서 매개 변수 값의 내보내기 요청을 보냅니다.
private async Task<string> PostExportRequest(
Guid reportId,
Guid groupId)
{
// For documentation purposes the export configuration is created in this method
// Ordinarily, it would be created outside and passed in
var paginatedReportExportConfiguration = new PaginatedReportExportConfiguration()
{
FormatSettings = new Dictionary<string, string>()
{
{"PageHeight", "14in"},
{"PageWidth", "8.5in" },
{"StartPage", "1"},
{"EndPage", "4"},
},
ParameterValues = new List<ParameterValue>()
{
{ new ParameterValue() {Name = "State", Value = "WA"} },
{ new ParameterValue() {Name = "City", Value = "Redmond"} },
},
};
var exportRequest = new ExportReportRequest
{
Format = FileFormat.PDF,
PaginatedReportExportConfiguration = paginatedReportExportConfiguration,
};
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<Export> PollExportRequest(
Guid reportId,
Guid groupId,
string exportId /* Get from the ExportToAsync response */,
int timeOutInMinutes,
CancellationToken token)
{
Export exportStatus = null;
DateTime startTime = DateTime.UtcNow;
const int secToMillisec = 1000;
do
{
if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
{
// Error handling for timeout and cancellations
return null;
}
var httpMessage =
await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
exportStatus = httpMessage.Body;
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 only populated when the status is either Running or NotStarted
var retryAfter = httpMessage.Response.Headers.RetryAfter;
var retryAfterInSec = retryAfter.Delta.Value.Seconds;
await Task.Delay(retryAfterInSec * secToMillisec);
}
}
// While not in a terminal state, keep polling
while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);
return exportStatus;
}
3단계 - 파일 가져오기
폴링이 URL을 반환하면 이 예제를 사용하여 받은 파일을 가져옵니다.
private async Task<ExportedFile> GetExportedFile(
Guid reportId,
Guid groupId,
Export export /* Get from the GetExportStatusAsync response */)
{
if (export.Status == ExportState.Succeeded)
{
var httpMessage =
await Client.Reports.GetFileOfExportToFileInGroupWithHttpMessagesAsync(groupId, reportId, export.Id);
return new ExportedFile
{
FileStream = httpMessage.Body,
ReportName = export.ReportName,
FileExtension = export.ResourceFileExtension,
};
}
return null;
}
public class ExportedFile
{
public Stream FileStream;
public string ReportName;
public string FileExtension;
}
엔드투엔드 예제
보고서를 내보내는 엔드투엔드 예제입니다. 이 예제는 다음과 같은 단계로 구성됩니다.
private async Task<ExportedFile> ExportPaginatedReport(
Guid reportId,
Guid groupId,
int pollingtimeOutInMinutes,
CancellationToken token)
{
try
{
var exportId = await PostExportRequest(reportId, groupId);
var export = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
if (export == null || export.Status != ExportState.Succeeded)
{
// Error, failure in exporting the report
return null;
}
return await GetExportedFile(reportId, groupId, export);
}
catch
{
// Error handling
throw;
}
}
고려 사항 및 제한 사항
Power BI 의미 체계 모델이 데이터 원본인 페이지 매긴 보고서 내보내기는 다음과 같은 경우 지원되지 않습니다.
- 호출자가 서비스 주체 프로필입니다.
- 의미 체계 모델의 데이터 원본 중 하나가 SSO(Single Sign-On)를 사용하도록 구성되고 유효한 ID가 제공되었습니다.
- Power BI 의미 체계 모델에는 Azure Analysis Services 또는 다른 Power BI 의미 체계 모델에 대한 DirectQuery가 있으며 효과적인 ID가 제공되었습니다.
SSO(Single Sign-On)를 사용하도록 구성된 Azure Analysis Services 데이터 원본이 있는 페이지 매긴 보고서 내보내기는 다음의 경우에 지원되지 않습니다.
- 호출자가 서비스 주체 프로필입니다.
- 호출자가 마스터 사용자이며 유효한 ID가 제공되었습니다.
유효한 ID를 사용하여 페이지를 매긴 보고서를 내보내려면 사용자 이름이 테넌트 Microsoft Entra ID의 기존 사용자여야 합니다.
보고서 내보내기는 사용자 액세스 토큰의 수명과 일치하는 60분으로 제한됩니다. 많은 양의 데이터를 내보낼 때 60분 표시 이후에 시간 초과 오류가 발생하면 적절한 필터를 사용하여 데이터의 양을 줄이는 것이 좋습니다.
온라인 Power BI 서비스에 게시된 페이지 매긴 보고서를 내보낼 때 파일 공유 URL 하이퍼링크(파일 공유 /UNC 경로)가 작동하지 않습니다.
관련 콘텐츠
고객 및 조직용 콘텐츠를 포함하는 방법을 검토합니다.