將分頁報表導出至檔案

發行項
02/04/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、Embedded 或 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）

使用已定義為數據來源的數據列層級安全性（RLS）的 Power BI 語意模型時，您可以匯出報表，顯示只有特定使用者可以看到的數據。例如，如果您要匯出以區域角色定義的銷售報表，您可以以程式設計方式篩選報表，以便只顯示特定區域。

若要使用 RLS 匯出，您必須擁有報表作為數據源使用的 Power BI 語意模型讀取許可權。

以下是提供 RLS 有效用戶名稱的範例。

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

單一登入 SQL 和 Dataverse （SSO）

在 Power BI 中，您可以選擇使用 SSO 設定 OAuth。當您這麼做時，檢視報表的用戶認證會用來擷取數據。要求標頭中的存取令牌不會用來存取數據。令牌必須與有效的身分識別一起傳入正文。

取得您想要存取之資源的正確存取令牌有時可能很棘手。

針對 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 語意模型具有可以直接查詢 Azure Analysis Services 或另一個 Power BI 語意模型的功能，並且已提供有效的身分識別。
在下列情況下，不支援匯出已啟用單一登錄的 Azure Analysis Services 數據源的編頁報表：
- 呼叫者是服務主體配置檔。
- 呼叫者是管理者，並提供了有效的身份識別。
若要匯出具有有效身分識別的編頁報表，用戶名稱必須是租使用者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 - 取得檔案

端對端範例

考慮和限制

相關內容

意見反應

其他資源