페이지를 매긴 보고서를 파일로 내보내기

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 사용

라이선스 요구 사항

• 내보내는 보고서는 프리미엄, 임베디드 또는 패브릭 용량으로 지원되는 작업 영역에 있어야 합니다.
• exportToFile API는 PPU(사용자 단위 Premium)제한된 지원을.

렌더링 이벤트

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

여론 조사

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

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

지원되는 기능

형식 설정

각 파일 형식에 대한 다양한 형식 설정을 지정합니다. 지원되는 속성과 값은 페이지 매김이 있는 보고서 URL 매개 변수의 디바이스 정보 매개 변수와 동일합니다.

다음은 두 가지 예입니다. 첫 번째는 보고서 페이지 크기를 사용하여 보고서의 처음 네 페이지를 .pptx 파일로 내보내는 것입니다. 두 번째 예제는 보고서의 세 번째 페이지를 .jpeg 파일로 내보내는 것입니다.

처음 네 페이지를 .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를 설정하는 옵션이 있습니다. 이렇게 하면 보고서를 보는 사용자에 대한 자격 증명이 데이터를 검색하는 데 사용됩니다. 요청 헤더의 액세스 토큰은 데이터에 액세스하는 데 사용되지 않습니다. 토큰은 포스트 본문의 효과적인 아이덴티티와 함께 전달되어야 합니다.

액세스하려는 리소스에 대한 올바른 액세스 토큰을 가져오는 것은 때로는 까다로울 수 있습니다.

• 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)exportToFile API를 사용하면 5분 동안 하나의 요청을 수 있습니다. 5분 기간 내에 여러 요청이 있으면 너무 많은 요청(429) 오류가 발생합니다.

코드 예제

코드 예제에 사용되는 Power BI API SDK는 여기에서다운로드할 수 있습니다.

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

1. 내보내기 요청 보내기
2. 투표
3. 파일을 가져옵니다.

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

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;
}

엔드 투 엔드 예제

보고서를 내보내는 엔드 투 엔드 예제입니다. 이 예제에는 다음 단계가 포함됩니다.

1. 내보내기 요청보냅니다.
2. 폴링.
3. 파일가져옵니다.

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 경로)가 작동하지 않습니다.

관련 콘텐츠

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

• 보고서를 파일로 내보내기
• 고객을 위한 포함
• 조직을 위한 포함