Eksportowanie raportu usługi Power BI do pliku

  • Artykuł

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

Uwaga

Eksportowanie raportu usługi Power BI do pliku przy użyciu interfejsu API exportToFile nie jest obsługiwane w przypadku warstwy Premium na użytkownika (PPU).

Przykłady użycia

Możesz użyć funkcji eksportu na kilka sposobów. 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ą zakładek można wyeksportować raport w określonym stanie, w tym skonfigurowane filtry, fragmentatory i inne ustawienia. 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. Aby uzyskać więcej informacji, zobacz Eksportowanie i wysyłanie wiadomości e-mail do raportu usługi Power BI przy użyciu usługi Power Automate

Korzystanie z interfejsu API

Wymagania dotyczące licencji

  • Eksportowany raport musi znajdować się w obszarze roboczym wspieranym przez pojemność Premium, Embedded lub Fabric.
  • Interfejs exportToFile API nie jest obsługiwany w przypadku warstwy Premium na użytkownika (PPU).

Ustawienia administratora

Przed użyciem interfejsu API sprawdź, czy są włączone następujące ustawienia dzierżawy administratora:

  • Eksportuj raporty jako prezentacje programu PowerPoint lub dokumenty PDF — domyślnie włączone.
  • Eksportuj raporty jako pliki obrazów — domyślnie wymagane tylko dla plików PNG i wyłączonych.

Zdarzenia renderowania

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.

Podczas sondowania interfejs API zwraca liczbę reprezentującą ilość wykonanej pracy. Praca w każdym zadaniu eksportu jest obliczana na podstawie sumy eksportów w zadaniu. Eksport obejmuje eksportowanie pojedynczej wizualizacji lub strony z zakładkami lub bez nich. Wszystkie eksporty mają taką samą wagę. Jeśli na przykład zadanie eksportu obejmuje eksportowanie raportu z 10 stron, a sondowanie zwraca wartość 70, oznacza to, że interfejs API przetworzył siedem z 10 stron w zadaniu eksportu.

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

W tej sekcji opisano sposób używania następujących obsługiwanych funkcji:

Wybieranie stron do wydrukowania

Określ strony, które mają być drukowane zgodnie z wartością Zwracaną przez strony pobierz lub Pobierz strony. Możesz również określić kolejność eksportowanych stron.

Eksportowanie strony lub pojedynczej wizualizacji

Możesz określić stronę lub pojedynczą wizualizację do wyeksportowania. Strony można eksportować z zakładkami lub bez tych zakładek.

W zależności od typu eksportu należy przekazać różne atrybuty do obiektu ExportReportPage . W poniższej tabeli określono, które atrybuty są wymagane dla każdego zadania eksportu.

Uwaga

Eksportowanie pojedynczej wizualizacji ma taką samą wagę jak eksportowanie strony (z zakładkami lub bez ich). Oznacza to, że pod względem obliczeń systemowych obie operacje mają tę samą wartość.

Atrybut Strona Pojedyncza wizualizacja Komentarze
bookmark Opcjonalnie Does not apply to. Służy do eksportowania strony w określonym stanie
pageName Applies to. Applies to. Użyj interfejsu API REST getPages lub interfejsu getPages API klienta.
visualName Does not apply to. Applies to. Istnieją dwa sposoby uzyskiwania nazwy wizualizacji:
  • Użyj interfejsu getVisuals API klienta.
  • Nasłuchiwanie i rejestrowanie zdarzenia wizualizacjiKlikwidowane, które jest wyzwalane po wybraniu wizualizacji. Aby uzyskać więcej informacji, zobacz Jak obsługiwać zdarzenia
    • .

    Zakładki

    Zakładki mogą służyć do zapisywania raportu w określonej konfiguracji, w tym zastosowanych filtrów i stanu wizualizacji raportu. Interfejs API exportToFile umożliwia programowe eksportowanie zakładki raportu na dwa sposoby:

    • Eksportowanie istniejącej zakładki

      Aby wyeksportować istniejącą zakładkę raportu, użyj name właściwości , unikatowego (z uwzględnieniem wielkości liter), który można uzyskać przy użyciu interfejsu API języka JavaScript zakładek.

    • Eksportowanie stanu raportu

      Aby wyeksportować bieżący stan raportu, użyj state właściwości . Na przykład możesz użyć metody zakładki bookmarksManager.capture , aby przechwycić zmiany wprowadzone przez określonego użytkownika do raportu, a następnie wyeksportować go w bieżącym stanie przy użyciu polecenia capturedBookmark.state.

    Uwaga

    Zakładki osobiste i filtry trwałe nie są obsługiwane.

    Filtry

    Za pomocą polecenia reportLevelFilters PowerBIReportExportConfiguration można wyeksportować raport w filtrowanym warunku.

    Aby wyeksportować filtrowany raport, wstaw parametry ciągu zapytania adresu URL, których chcesz użyć jako filtru, w polu ExportFilter. Po wprowadzeniu ciągu należy usunąć ?filter= część parametru zapytania adresu URL.

    Tabela zawiera kilka przykładów składni ciągów, które można przekazać do .ExportFilter

    Filtr Składnia Przykład
    Wartość w polu Tabela/Pole eq "value" Store/Territory eq 'NC'
    Wiele wartości w polu Table/Field in ('value1', 'value2') Store/Territory in ('NC', 'TN')
    Unikatowa wartość w jednym polu i inna unikatowa wartość w innym polu Table/Field1 eq "value1" i Table/Field2 eq "value2" Store/Territory eq "NC" i Store/Chain eq "Fashions Direct"

    Uwierzytelnianie

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

    Zabezpieczenia na poziomie wiersza (RLS)

    Za pomocą zabezpieczeń na poziomie wiersza 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 za pomocą ról regionalnych, możesz programowo filtrować raport tak, aby był wyświetlany tylko w określonym regionie.

    Aby wyeksportować przy użyciu zabezpieczeń na poziomie wiersza, musisz mieć następujące uprawnienia:

    • Uprawnienia do zapisu i udostępniania dalej dla modelu semantycznego, z który raport jest połączony
    • Członek obszaru roboczego lub administrator obszaru roboczego, w którym znajduje się raport

    Ochrona danych

    Formaty plików PDF i pptx obsługują etykiety poufności. W przypadku eksportowania raportu z etykietą poufności do pliku PDF lub pptx wyeksportowany plik wyświetla raport z etykietą poufności.

    Nie można wyeksportować raportu z etykietą poufności do pliku PDF lub pptx przy użyciu jednostki usługi.

    Lokalizacja

    W przypadku korzystania z interfejsu exportToFile API możesz przekazać odpowiednie ustawienia regionalne. Ustawienia lokalizacji wpływają na sposób wyświetlania raportu, na przykład przez zmianę formatowania zgodnie z wybranym lokalnym.

    Powiązanie dynamiczne

    Aby wyeksportować raport, gdy jest on połączony z semantycznym modelem innym niż domyślny model semantyczny, określ wymagany identyfikator zestawu danych w parametrze datasetToBind podczas wywoływania interfejsu API. Przeczytaj więcej na temat powiązania dynamicznego.

    Żądania współbieżne

    Interfejs exportToFile API obsługuje ograniczoną liczbę współbieżnych żądań. Maksymalna liczba obsługiwanych żądań współbieżnych wynosi 500 na pojemność. 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. Jednocześnie przetwarzane są tylko pięć stron raportu. Jeśli na przykład eksportujesz raport z 50 stronami, zadanie eksportu jest przetwarzane w 10 interwałach sekwencyjnych. Podczas optymalizowania zadania eksportu warto rozważyć równoległe wykonanie kilku zadań.

    Przykłady kodu

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

    1. Wysyłanie żądania eksportu.
    2. Sondowanie.
    3. Pobieranie pliku.
    4. Za pomocą strumienia plików.

    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ślonej strony.

    private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId,
    FileFormat format,
    IList<string> pageNames = null, /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
    var powerBIReportExportConfiguration = new PowerBIReportExportConfiguration
    {
        Settings = new ExportReportSettings
        {
            Locale = "en-us",
        },
        // Note that page names differ from the page display names
        // To get the page names use the GetPages REST API
        Pages = pageNames?.Select(pn => new ExportReportPage(Name = pn)).ToList(),
        // ReportLevelFilters collection needs to be instantiated explicitly
        ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

    };

    var exportRequest = new ExportReportRequest
    {
        Format = format,
        PowerBIReportConfiguration = powerBIReportExportConfiguration,
    };

    // The 'Client' object is an instance of the Power BI .NET SDK
    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<HttpOperationResponse<Export>> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the PostExportRequest response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    HttpOperationResponse<Export> httpMessage = null;
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int c_secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations 
            return null;
        }

        // The 'Client' object is an instance of the Power BI .NET SDK
        httpMessage = await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
        exportStatus = httpMessage.Body;

        // You can track the export progress using the PercentComplete that's part of the response
        SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(), exportStatus.PercentComplete);
        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 not always populated
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;
            await Task.Delay(retryAfterInSec * c_secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return httpMessage;
}

    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 PollExportRequest response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        // The 'Client' object is an instance of the Power BI .NET SDK
        var fileStream = await Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
        return new ExportedFile
        {
            FileStream = fileStream,
            FileSuffix = export.ResourceFileExtension,
        };
    }
    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string FileSuffix;
}

    Krok 4. Korzystanie ze strumienia plików

    Gdy masz strumień plików, możesz obsłużyć go w taki sposób, aby najlepiej pasował do Twoich potrzeb. Możesz na przykład wysłać wiadomość e-mail lub użyć jej do pobrania wyeksportowanych raportów.

    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> ExportPowerBIReport(
	Guid reportId,
	Guid groupId,
	FileFormat format,
	int pollingtimeOutInMinutes,
	CancellationToken token,
	IList<string> pageNames = null,  /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
	const int c_maxNumberOfRetries = 3; /* Can be set to any desired number */
	const int c_secToMillisec = 1000;
	try
	{
		Export export = null;
		int retryAttempt = 1;
		do
		{
			var exportId = await PostExportRequest(reportId, groupId, format, pageNames, urlFilter);
			var httpMessage = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
			export = httpMessage.Body;
			if (export == null)
			{
				// Error, failure in exporting the report
				return null;
			}
			if (export.Status == ExportState.Failed)
			{
				// Some failure cases indicate that the system is currently busy. The entire export operation can be retried after a certain delay
				// In such cases the recommended waiting time before retrying the entire export operation can be found in the RetryAfter header
				var retryAfter = httpMessage.Response.Headers.RetryAfter;
				if(retryAfter == null)
				{
				    // Failed state with no RetryAfter header indicates that the export failed permanently
				    return null;
                }

                var retryAfterInSec = retryAfter.Delta.Value.Seconds;
                await Task.Delay(retryAfterInSec * c_secToMillisec);
            }
        }
        while (export.Status != ExportState.Succeeded && retryAttempt++ < c_maxNumberOfRetries);

        if (export.Status != ExportState.Succeeded)
        {
            // Error, failure in exporting the report
            return null;
        }

        var exportedFile = await GetExportedFile(reportId, groupId, export);

        // Now you have the exported file stream ready to be used according to your specific needs
        // For example, saving the file can be done as follows:
        /*
            var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;

            using (var fileStream = File.Create(pathOnDisk))
            {
                exportedFile.FileStream.CopyTo(fileStream);
            }
        */

        return exportedFile;
    }
    catch
    {
        // Error handling
        throw;
    }
}

    Rozważania i ograniczenia

    • Obciążenie operacji interfejsu API eksportu jest oceniane jako wolno działająca operacja w tle, zgodnie z opisem w temacie Ocena obciążenia pojemności Premium.
    • Wszystkie powiązane modele semantyczne w eksportowanym raporcie muszą znajdować się w pojemności Premium lub Embedded, w tym modele semantyczne z połączeniem zapytania bezpośredniego.
    • Wyeksportowane raporty nie mogą przekraczać rozmiaru pliku o rozmiarze 250 MB.
    • Podczas eksportowania do pliku .png etykiety poufności nie są obsługiwane.
    • Liczba eksportów (pojedynczych wizualizacji lub stron raportu), które można uwzględnić w jednym wyeksportowanym raporcie, wynosi 50 (bez eksportowania raportów podzielonych na strony). Jeśli żądanie zawiera więcej eksportów, interfejs API zwraca błąd i zadanie eksportu zostanie anulowane.
    • Zakładki osobiste i filtry trwałe nie są obsługiwane w przypadku eksportowania raportu usługi Power BI do pliku.
    • Interfejs exportToFile API eksportuje raport z wartością domyślną, jeśli jest używany bez zakładek lub reportLevelFilters.
    • Wizualizacje usługi Power BI wymienione tutaj nie są obsługiwane. Podczas eksportowania raportu zawierającego te wizualizacje części raportu zawierające te wizualizacje nie są renderowane i wyświetlają symbol błędu.
      • Niecertyfikowane wizualizacje niestandardowe usługi Power BI
      • Wizualizacje języka R
      • PowerApps
      • Wizualizacje języka Python
      • Power Automate
      • Wizualizacja raportu podzielonego na strony
      • Visio
      • Wizualizacje ArcGIS

    Powiązana zawartość

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

    Więcej pytań? Wypróbuj Społeczność usługi Power BI