將編頁報表匯出至檔案

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. 傳送匯出要求。
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) 並提供有效的身分識別。
  • Power BI 語意模型有對 Azure Analysis Services 或另一個 Power BI 語意模型的 DirectQuery，並提供有效的身分識別。

• 在下列情況下，不支援匯出的編頁報表具有已設定啟用單一登入的 Azure Analysis Services 資料來源：

  • 呼叫端是服務主體設定檔。
  • 呼叫端是主要使用者，並提供有效的身分識別。

• 若要匯出具有有效身分識別的編頁報表，使用者名稱必須是租用戶的 Microsoft Entra ID 的現有使用者。

• 報表的匯出限制為 60 分鐘，這符合使用者存取權杖的存留期。 如果您在匯出大量資料時收到超過 60 分鐘標記的逾時錯誤，請考慮使用適當的篩選來減少資料量。

• 在 Power BI 服務線上匯出已發佈的編頁報表時，檔案共用 URL 超連結 (檔案共用 /UNC 路徑) 無法運作。

相關內容

檢閱如何為您的客戶與組織內嵌內容：

• 將報表匯出至檔案
• 對客戶進行內嵌
• 為組織內嵌