将分页报表导出为文件
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 路径)不起作用。
相关内容
查看如何为客户和组织嵌入内容: