Eksportowanie raportu podzielonego na strony do pliku

  • Artykuł

Interfejs exportToFile API umożliwia eksportowanie raportu podzielonego na strony usługi Power BI przy użyciu wywołania REST. Obsługiwane są następujące formaty plików:

  • .pptx (PowerPoint)

  • .pdf (i dostępny plik PDF lub PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .Csv

  • .Xml

  • .Mhtml

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

    • .tiff (wartość domyślna)
    • .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 wyzwala zadanie eksportu. Zadanie może wyeksportować wyświetlany raport jako plik 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, może upłynąć trochę czasu zanim plik będzie dostępny.

  • Załącznik wiadomości e-mail — wysyłaj automatyczną wiadomość e-mail w ustalonych 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 dotyczące licencji

Renderowanie zdarzeń

Aby upewnić się, że eksport nie rozpoczyna się przed zakończeniem renderowania wizualizacji, użyj interfejsu API zdarzeń renderowania i rozpocznij eksport tylko po zakończeniu renderowania.

Sondowanie

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

Po zakończeniu eksportowania wywołanie interfejsu API sondowania zwraca adres URL usługi Power BI na potrzeby pobierania 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 informacji o urządzeniu dla parametrów adresu URL raportu podzielonego na strony.

Poniżej przedstawiono 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 pliku pptx

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

Eksportowanie trzeciej strony do pliku JPEG

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

Parametry raportu

Interfejs API umożliwia exportToFile programowe eksportowanie raportu z zestawem parametrów raportu. Odbywa się to przy użyciu funkcji parametrów 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 z zabezpieczeniami na poziomie wiersza zdefiniowanym 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 zabezpieczeń na poziomie wiersza, musisz mieć uprawnienie do odczytu dla semantycznego modelu usługi Power BI, którego raport używa jako źródła danych.

Oto przykład podawania obowiązującej nazwy użytkownika dla 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 ustawić protokół OAuth przy użyciu logowania jednokrotnego. Gdy to zrobisz, poświadczenia użytkownika wyświetlający 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 to https://database.windows.net.
  • W przypadku usługi Dataverse zasób jest https:// adresem twojego środowiska. Na przykład https://contoso.crm.dynamics.com.

Uzyskaj dostęp do interfejsu API tokenu 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

Funkcja exportToFile obsługuje ograniczoną liczbę współbieżnych żądań. Maksymalna liczba współbieżnych żądań renderowania raportu podzielonego na strony 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 warstwy Premium na użytkownika (PPU)exportToFile interfejs API umożliwia tylko jedno żądanie w pięciominutowym oknie. Wiele żądań w oknie pięciu minut powoduje błąd Zbyt wiele żądań (429).

Przykłady kodu

Zestaw SDK interfejs API usługi Power BI 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. Sondowania.
  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ślonych wartości parametrów zakresu, rozmiaru i 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 kompleksowego

Jest to kompleksowe 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;
    }
}

Rozważania 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 z włączonym logowaniem jednokrotnym i udostępniono efektywną 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 podzielony na strony z obowiązującą tożsamością, nazwa użytkownika musi być istniejącym użytkownikiem z identyfikatora microsoft entra dzierżawy.

  • 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 adresu URL udziału plików (ścieżka udziału plików /UNC) nie działa podczas eksportowania opublikowanego raportu podzielonego na strony w trybie usługa Power BI online.

Powiązana zawartość

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