将 Power BI 报表导出到文件

API exportToFile 允许使用 REST 调用导出 Power BI 报表。 支持以下文件格式：

• .pptx （PowerPoint）
• .pdf
• .png
  • 导出到 .png时，将包含多个页的报表压缩到 .zip 文件中
  • .zip 中的每个文件都表示报表页
  • 页面名称与 Get Pages API 或 Get Pages in Group API 的返回值相同。

用法示例

可以通过多种方式使用导出功能。 下面是几个示例：

• “发送到打印”按钮 - 在应用程序中，创建在单击时触发导出作业的按钮。 该作业可以将已查看的报表导出为 .pdf 或 .pptx。 完成后，用户可以以下载的形式接收文件。 使用书签可以导出处于特定状态的报表，包括配置的筛选器、切片器和其他设置。 由于 API 是异步的，因此可能需要一些时间才能使文件可用。

• 电子邮件附件 - 在设置的时间间隔发送自动电子邮件，附带 .pdf 报表。 如果要自动向高管发送每周报表，此方案非常有用。 有关详细信息，请参阅 使用 Power Automate 导出和通过电子邮件发送 Power BI 报表

使用应用程序编程接口 (API)

许可要求

• 要导出的报表必须位于由高级版或嵌入版容量支持的工作区中。
• exportToFile API 不支持用于高级每个用户（PPU）。

管理员设置

使用 API 之前，请验证是否启用了以下 管理员租户设置 ：

• 将报表导出为 PowerPoint 演示文稿或 PDF 文档 - 默认启用。
• 将报表导出为图像文件 - 仅适用于 .png 文件，且默认禁用。

“呈现”事件

若要确保在视觉对象完成呈现之前不开始导出，请使用 “呈现”事件 API ，并且仅在呈现完成后才开始导出。

投票

API 是异步的。 调用 exportToFile API 时，会触发导出作业。 在导出作业触发后，使用轮询来跟踪此作业，直到它完成。

在轮询期间，API 返回一个数字，表示已完成的工作量。 每个导出作业中的工时是根据作业中的导出总数计算的。 导出包括导出单个视觉对象或包含或不带书签的页面。 所有导出项目的权重都相同。 例如，如果导出作业包括导出包含 10 页的报表，轮询返回 70，则表示 API 在导出作业中的 10 个页面中处理了 7 个。

在导出完成后，轮询 API 调用返回用于获取文件的 Power BI URL。 该 URL 有效 24 小时。

支持的功能

本部分介绍如何使用以下受支持的功能：

• 选择要打印的页面
• 导出页面或单个视觉对象
• Bookmarks
• 筛选器
• 身份验证
• 行级别安全性 （RLS）
• 数据保护
• 本地化
• 动态绑定

选择要打印的页面

根据 Get Pages 或 Get Pages in Group 的返回值指定要打印的页面。 还可以指定要导出的页面的顺序。

导出页面或单个视觉对象

可以指定要导出的页面或单个视觉对象。 可以使用或不使用书签导出页面。

根据导出的类型，需要将不同的属性传递给 ExportReportPage 对象。 下表指定每个导出作业需要哪些属性。

Attribute	页	单个视觉对象	注释
bookmark	可选		用于导出处于特定状态的页面
pageName			使用 GetPages REST API 或 getPages 客户端 API。
visualName			可通过两种方法获取视觉对象的名称： getVisuals使用客户端 API。 侦听并记录 visualClicked 事件，该事件在选择视觉对象时触发。 有关详细信息，请参阅 如何处理事件 .

Bookmarks

书签 可用于在特定配置中保存报表，包括应用的筛选器和报表视觉对象的状态。 可以通过两种方式使用 exportToFile API 以编程方式导出报表的书签：

• 导出现有书签

  若要导出现有的 报表书签，请使用 name 属性，该属性是唯一的（区分大小写）标识符，可以通过 书签 JavaScript API 获取。

• 导出报表的状态

  若要导出报表的当前状态，请使用该 state 属性。 例如，您可以使用书签的 bookmarksManager.capture 方法来捕获特定用户对报告所做的更改，然后使用 capturedBookmark.state 将其以当前状态导出。

过滤 器

在 reportLevelFiltersPowerBIReportExportConfiguration 中使用，可以在筛选条件中导出报表。

若要导出筛选的报表，请将要用作筛选器的 URL 查询字符串参数 插入 到 ExportFilter。 输入字符串时，必须删除 ?filter= URL 查询参数的一部分。

该表包含一些可以传递给 ExportFilter的字符串的语法示例。

Authentication

只能使用用户（或主用户）或服务主体进行身份验证。

数据保护

.pdf 和 .pptx 格式支持 敏感度标签。 如果将具有敏感度标签的报表导出到 .pdf 或 .pptx，则导出的文件将显示具有其敏感度标签的报表。

使用服务主体无法将带有敏感性标签的报表导出为.pdf或.pptx文件。

本地化

使用 exportToFile API 时，可以传递所需的区域设置。 本地化设置会影响报表的显示方式，例如，根据所选本地更改格式设置。

动态绑定

为了将报表导出到非默认的语义模型，调用 API 时需要在 datasetToBind 参数中指定所需的数据集 ID。 详细了解动态绑定。

并发请求

API exportToFile 支持有限数量的并发请求。 支持的最大并发请求数是每个容量 500 个。 为了避免超出限制并收到过多的请求（429）错误，请随着时间的推移或跨容量分配负载。 只有报表中的五页会被同时处理。 例如，如果要导出包含 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 操作负载被评估为一个运行缓慢的后台操作，如高级容量负载评估中所述。
• 要导出的报表中的所有相关语义模型必须驻留在高级容量或嵌入式容量上，包括具有直接查询连接的语义模型。
• 导出的报表不能超过文件大小 250 MB。
• 导出到 .png时，不支持敏感度标签。
• 可以包含在单个导出报表中的导出数（单个视觉对象或报表页）为 50（不包括导出分页报表）。 如果请求包含更多导出，API 将返回错误，并取消导出作业。
• Power BI 报表导出到文件不支持个人书签和持久性筛选器。
• 如果不使用书签或报告级别过滤器时，exportToFile API 将导出具有默认值的报表。
• 不支持导出连接到至少一个启用了单一登录（SSO）的外部数据源的一个或多个复合语义模型的 Power BI 报表。 导出时，视觉对象可能无法正确呈现。
• 使用 REST API 导出具有exportToFile的报表时，动态绑定语义模型不能是具有对 SQL Server Analysis Services（SSAS）的直接查询的复合模型。
• 此处列出的 Power BI 视觉对象不受支持。 导出包含这些视觉对象的报表时，包含这些视觉对象的报表部分不会呈现，并显示错误符号。
  • 未经认证的 Power BI 自定义视觉对象
  • R 视觉对象
  • PowerApps
  • Python 视觉对象
  • Power Automate
  • 分页报表视觉对象
  • Visio
  • ArcGIS 可视化

相关内容

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

• 将分页报表导出到文件
• 为客户嵌入内容
• 为组织嵌入内容
• 使用 Power Automate 导出和通过电子邮件发送 Power BI 报表

更多问题？ 试用 Power BI 社区