Udostępnij za pośrednictwem

Eksportowanie raportu podzielonego na strony do pliku

  • Artykuł

Interfejs API exportToFile umożliwia eksportowanie paginowanego raportu Power BI za pomocą wywołania REST. Obsługiwane są następujące formaty plików:

  • .pptx (PowerPoint)

  • .pdf (i Accessible PDF lub PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .csv

  • .xml

  • .mhtml

  • obrazu
    Podczas eksportowania do obrazu ustaw format obrazu za pomocą ustawienia format OutputFormat. Obsługiwane wartości OutputFormat to:

    • .tiff (ustawienie domyślne)
    • .bmp
    • .emf
    • .gif
    • .jpeg
    • .png

Przykłady użycia

Funkcję eksportowania można używać na różne sposoby. Oto kilka przykładów:

  • przycisk 'Wyślij do drukowania' — w aplikacji utwórz przycisk, który po kliknięciu rozpoczyna zadanie eksportu. Zadanie może wyeksportować wyświetlany raport jako .pdf lub .pptx. Po zakończeniu użytkownik może otrzymać plik jako plik do pobrania. Za pomocą parametrów raportu i ustawień formatu można wyeksportować raport w określonym stanie, w tym przefiltrowane dane, niestandardowe rozmiary stron i inne ustawienia specyficzne dla formatu. Ponieważ interfejs API jest asynchroniczny, udostępnienie pliku może zająć trochę czasu.

  • Załącznik wiadomości e-mail — wysyłaj automatyczną wiadomość e-mail w określonych odstępach czasu z dołączonym raportem .pdf. Ten scenariusz może być przydatny, jeśli chcesz zautomatyzować wysyłanie cotygodniowego raportu do kadry kierowniczej.

Korzystanie z interfejsu API

Wymagania licencyjne

  • Eksportowany raport musi znajdować się w obszarze roboczym wspieranym przez pojemność Premium, Embedded lub Fabric.
  • Interfejs API exportToFile ma ograniczoną obsługę w Premium dla pojedynczego użytkownika (PPU).

Renderowanie zdarzeń

Aby upewnić się, że eksport nie zacznie się przed zakończeniem renderowania wizualizacji, użyj interfejsu API zdarzeń "Renderowanie" i upewnij się, że eksport rozpocznie się dopiero po zakończeniu renderowania.

Sondowanie

Interfejs API jest asynchroniczny. Po wywołaniu interfejsu API exportToFile wyzwala ono zadanie eksportu. Po uruchomieniu zadania eksportu użyj ankietowania, aby śledzić zadanie, dopóki nie zostanie ukończone.

Po zakończeniu eksportu, wywołanie API typu polling zwraca adres URL Power BI do pobrania pliku. Adres URL jest dostępny przez 24 godziny.

Obsługiwane funkcje

Ustawienia formatu

Określ różne ustawienia formatu dla każdego formatu pliku. Obsługiwane właściwości i wartości są równoważne parametrom Informacje o urządzeniu parametrów adresu URL raportu podzielonego na strony.

Oto dwa przykłady. Pierwszy to eksportowanie pierwszych czterech stron raportu przy użyciu rozmiaru strony raportu do pliku .pptx. Drugi przykład dotyczy eksportowania trzeciej strony raportu do pliku .jpeg.

Eksportowanie pierwszych czterech stron do .pptx

{
      "format": "PPTX",
      "paginatedReportConfiguration":{
            "formatSettings":{
                  "UseReportPageSize": "true",
                  "StartPage": "1",
                  "EndPage": "4"
            }
      }
}

Eksportowanie trzeciej strony do .jpeg

{
      "format": "IMAGE",
      "paginatedReportConfiguration":{
            "formatSettings":{
                  "OutputFormat": "JPEG",
                  "StartPage": "3",
                  "EndPage": "3"
            }
      }
}

Parametry raportu

Interfejs API exportToFile umożliwia programowe eksportowanie raportu z zestawem parametrów raportu. Odbywa się to przy użyciu możliwości parametru raportu .

Oto przykład ustawiania wartości parametrów raportu.

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "parameterValues":[
                  {"name": "State", "value": "WA"},
                  {"name": "City", "value": "Seattle"},
                  {"name": "City", "value": "Bellevue"},
                  {"name": "City", "value": "Redmond"}
            ]
      }
}

Uwierzytelnianie

Możesz uwierzytelnić się przy użyciu użytkownika (lub użytkownika głównego) lub jednostki usługi .

Zabezpieczenia na poziomie wiersza (RLS)

W przypadku korzystania z semantycznego modelu usługi Power BI, który ma zabezpieczenia na poziomie wiersza jako źródło danych, można wyeksportować raport przedstawiający dane widoczne tylko dla niektórych użytkowników. Jeśli na przykład eksportujesz raport sprzedaży zdefiniowany z rolami regionalnymi, możesz programowo filtrować raport tak, aby wyświetlany był tylko określony region.

Aby wyeksportować przy użyciu RLS, musisz mieć uprawnienie do odczytu semantycznego modelu usługi Power BI, którego raport używa jako źródła danych.

Oto przykład podawania skutecznej nazwy użytkownika dla RLS (zabezpieczeń na poziomie wiersza).

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

Logowanie jednokrotne SQL i usługa Dataverse (SSO)

W usłudze Power BI możesz skonfigurować OAuth z użyciem SSO (logowania jednokrotnego). Gdy to zrobisz, poświadczenia użytkownika wyświetlającego raport są używane do pobierania danych. Token dostępu w nagłówku żądania nie jest używany do uzyskiwania dostępu do danych. Token musi zostać przekazany z obowiązującą tożsamością w treści wpisu.

Uzyskanie poprawnego tokenu dostępu dla zasobu, do którego chcesz uzyskać dostęp, czasami może być trudne.

  • W przypadku usługi Azure SQL zasób jest https://database.windows.net.
  • W przypadku usługi Dataverse zasobem jest adres https:// danego środowiska. Na przykład https://contoso.crm.dynamics.com.

Uzyskaj dostęp do API tokenów przy użyciu metody AuthenticationContext.AcquireTokenAsync.

Oto przykład dostarczania obowiązującej tożsamości (nazwy użytkownika) z tokenem dostępu.

{
       "format":"PDF",
       "paginatedReportConfiguration":{
          "formatSettings":{
             "AccessiblePDF":"true",
             "PageHeight":"11in",
             "PageWidth":"8.5in",
             "MarginBottom":"2in"
          },
          "identities":[
             {
                "username":"john@contoso.com",
                "identityBlob": {
                "value": "eyJ0eX....full access token"
         }
        }
     ]
   }
}

Żądania współbieżne

exportToFile obsługuje ograniczoną liczbę współbieżnych żądań. Maksymalna liczba jednoczesnych żądań renderowania raportu stronicowanego wynosi 500. Aby uniknąć przekroczenia limitu i błędu zbyt wielu żądań (429), należy rozłożyć obciążenie w czasie lub w różnych pojemnościach.

W przypadku Premium Per User (PPU)interfejs API exportToFile umożliwia tylko jedno żądanie w oknie pięciominutowym. Wiele żądań w ciągu pięciu minut powoduje błąd Zbyt wiele żądań (429).

Przykłady kodu

Zestaw SDK interfejsu API usługi Power BI, który jest używany w przykładach kodu, można pobrać tutaj.

Podczas tworzenia zadania eksportu należy wykonać trzy kroki:

  1. Wysyłanie żądania eksportu.
  2. Sondowanie.
  3. Pobieranie pliku.

Ta sekcja zawiera przykłady dla każdego kroku.

Krok 1. Wysyłanie żądania eksportu

Pierwszym krokiem jest wysłanie żądania eksportu. W tym przykładzie żądanie eksportu jest wysyłane dla określonego zakresu stron, rozmiaru i wartości parametrów raportu.

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;
}

Krok 2. Sondowanie

Po wysłaniu żądania eksportu użyj sondowania, aby określić, kiedy plik eksportu, na który czekasz, jest gotowy.

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;
}

Krok 3. Pobieranie pliku

Gdy sondowanie zwróci adres URL, użyj tego przykładu, aby pobrać odebrany plik.

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;
}

Przykład od końca do końca

Jest to kompleksowy przykład eksportowania raportu. Ten przykład obejmuje następujące etapy:

  1. Wysyłanie żądania eksportu.
  2. sondowanie.
  3. Pobieranie pliku.
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;
    }
}

Zagadnienia i ograniczenia

  • Eksportowanie raportu podzielonego na strony z semantycznym modelem usługi Power BI jako źródła danych nie jest obsługiwane w następujących przypadkach:

    • Obiekt wywołujący jest profilem jednostki usługi .
    • Jedno ze źródeł danych modelu semantycznego jest skonfigurowane tak, aby obsługiwało logowanie jednokrotne (SSO), i udostępniono skuteczną tożsamość.
    • Model semantyczny usługi Power BI ma tryb DirectQuery do usług Azure Analysis Services lub do innego semantycznego modelu usługi Power BI i udostępniono efektywną tożsamość.

  • Eksportowanie raportu podzielonego na strony ze źródłem danych usług Azure Analysis Services skonfigurowanym z włączonym logowaniem jednokrotnym nie jest obsługiwane w następujących przypadkach:

    • Obiekt wywołujący jest profilem jednostki usługi .
    • Obiekt wywołujący jest użytkownikiem głównym i udostępniono efektywną tożsamość.

  • Aby wyeksportować raport stronicowany z odpowiednią tożsamością, nazwa użytkownika musi być istniejącym użytkownikiem usługi Microsoft Entra ID Twojego dzierżawcy.

  • Eksportowanie raportu jest ograniczone do 60 minut, co odpowiada okresowi istnienia tokenu dostępu użytkownika. Jeśli podczas eksportowania dużych ilości danych wystąpi błąd przekroczenia limitu czasu po upływie 60 minut, rozważ zmniejszenie ilości danych przy użyciu odpowiednich filtrów.

  • Hiperlink URL udostępniania plików (ścieżka udostępniania plików /UNC) nie działa podczas eksportowania opublikowanego raportu stronicowanego w usłudze Power BI.

Powiązana zawartość

Zapoznaj się ze sposobem osadzania zawartości dla klientów i organizacji: