将分页报表导出为文件

项目
02/06/2025

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、嵌入式或 Fabric 容量支持的工作区中。
exportToFile API 在 Premium Per User (PPU) 中具有有限支持。

呈现事件

若要确保在视觉对象完成呈现之前导出不会开始，请使用 “呈现”事件 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)

当使用在 Power BI 中已为数据源定义行级别安全性（RLS）的语义模型时，可以导出显示仅对特定用户可见数据的报表。例如，如果要导出使用区域角色定义的销售报表，则可以以编程方式筛选报表，以便仅显示特定区域。

若要使用 RLS 导出，必须具有报表用作数据源的 Power BI 语义模型的读取权限。

下面是为 RLS 提供有效用户名的示例。

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "identities": [
                  {"username": "john@contoso.com"}
            ]
      }
}

单一登录 SQL 和 Dataverse (SSO)

在 Power BI 中，可以选择使用 SSO 设置 OAuth。当你这样做时，用于查看报告的用户凭据会被用于检索数据。请求标头中的访问令牌不用于访问数据。需要将令牌与 post 正文中的有效标识一起传入。

获取要访问的资源的正确访问令牌有时可能很棘手。

对于 Azure SQL，资源是 https://database.windows.net。
对于 Dataverse，资源是环境的 https:// 地址。例如，https://contoso.crm.dynamics.com。

使用 AuthenticationContext.AcquireTokenAsync 方法访问令牌 API。

下面是使用访问令牌提供有效标识（用户名）的示例。

{
       "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）错误，请随着时间的推移或跨容量分配负载。

使用 Premium Per User (PPU) 时，exportToFile API 在五分钟内只允许一个请求。五分钟窗口中的多个请求导致 请求过多（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），并提供了有效的标识。
- Power BI 语义模型可以通过 DirectQuery 连接到 Azure Analysis Services 或其他 Power BI 语义模型，并且已经提供了一有效的身份。
在以下情况下，导出已配置 Azure Analysis Services 数据源且启用了单一登录（SSO）的分页报表不受支持：
- 调用方是服务主体配置文件。
- 调用方是主用户，并且提供了有效的标识。
若要导出具有有效标识的分页报表，用户名必须是租户Microsoft Entra ID 中的现有用户。
报表的导出限制为 60 分钟，这与用户访问令牌的生存期相匹配。如果在导出大量数据时出现超过60分钟的超时错误，请考虑使用合适的筛选条件减少数据量。
联机导出 Power BI 服务上发布的分页报表时，文件共享 URL 超链接（文件共享 /UNC 路径）不起作用。

查看如何为客户和组织嵌入内容：

通过

将分页报表导出为文件

用法示例

使用 API

许可证要求

呈现事件

投票

支持的功能

格式设置

将前四页导出为 .pptx

将第三页导出到.jpeg

报表参数

认证

行级别安全性 (RLS)

单一登录 SQL 和 Dataverse (SSO)

并发请求

代码示例

步骤 1 - 发送导出请求

步骤 2 - 轮询

步骤 3 - 获取文件

端到端示例

注意事项和限制

反馈

其他资源

通过

将分页报表导出为文件

用法示例

使用 API

许可证要求

呈现事件

投票

支持的功能

格式设置

将前四页导出为 .pptx

将第三页导出到.jpeg

报表参数

认证

行级别安全性 (RLS)

单一登录 SQL 和 Dataverse (SSO)

并发请求

代码示例

步骤 1 - 发送导出请求

步骤 2 - 轮询

步骤 3 - 获取文件

端到端示例

注意事项和限制

相关内容

反馈

其他资源