Power BI-jelentés exportálása fájlba

  • Cikk

Az exportToFile API REST-hívással teszi lehetővé a Power BI-jelentések exportálását. A következő fájlformátumok támogatottak:

  • .pptx (PowerPoint)
  • .Pdf
  • .png
    • .png-fájlba való exportáláskor a többoldalas jelentések .zip fájlba lesznek tömörítve
    • A .zip fájl minden fájlja egy jelentésoldalt jelöl
    • A lapnevek megegyeznek a Lapok lekérése vagy a Lapok lekérése csoport API-kban visszaadott értékeivel

Megjegyzés:

A Power BI-jelentések exportálása egy fájlba az exportToFile API használatával nem támogatott a Premium Per User (PPU) esetében.

Felhasználási példák

Az exportálási funkciót többféleképpen is használhatja. Íme néhány példa:

  • Küldés nyomtatásra gomb – Az alkalmazásban hozzon létre egy gombot, amelyre kattintva egy exportálási feladat aktiválódik. A feladat exportálhatja a megtekintett jelentést .pdf vagy .pptx formátumban. Ha elkészült, a felhasználó letöltheti a fájlt. Könyvjelzők használatával exportálhatja a jelentést egy adott állapotban, beleértve a konfigurált szűrőket, szeletelőket és egyéb beállításokat. Mivel az API aszinkron, hosszabb időt is igénybe vehet, amíg a fájl elérhetővé válik.

  • E-mail melléklet – Automatikus e-mail küldése megadott időközönként, csatolt .pdf jelentéssel. Ez a forgatókönyv akkor lehet hasznos, ha egy heti jelentést szeretne automatizálni a vezetőknek. További információ: Power BI-jelentés exportálása és e-mail küldése a Power Automate használatával

Az API használata

License requirements

  • Az exportált jelentésnek egy Prémium, Embedded vagy Fabric kapacitással rendelkező munkaterületen kell lennie.
  • Az exportToFile API nem támogatott a Felhasználónkénti Premium (PPU) esetében.

Rendszergazdai beállítások

Az API használata előtt ellenőrizze, hogy engedélyezve vannak-e a következő rendszergazdai bérlői beállítások :

  • Jelentések exportálása PowerPoint-bemutatóként vagy PDF-dokumentumként – Alapértelmezés szerint engedélyezve van.
  • Jelentések exportálása képfájlokként – Csak .png esetén szükséges, és alapértelmezés szerint le van tiltva.

"Renderelés" események

Annak érdekében, hogy az exportálás ne kezdődjön el, mielőtt a vizualizáció befejeződik, használja a "Rendering" events API-t , és csak a renderelés befejezésekor kezdje el az exportálást.

ciklikus lekérdezések

Az API aszinkron. Az exportToFile API meghívásakor egy exportálási feladatot aktivál. Az exportálási feladat aktiválása után a lekérdezéssel nyomon követheti a feladatot, amíg be nem fejeződik.

A lekérdezés során az API egy számot ad vissza, amely a befejezett munka mennyiségét jelöli. Az egyes exportálási feladatokban lévő munka kiszámítása a feladatban lévő exportálások teljes száma alapján történik. Az exportálás magában foglalja egyetlen vizualizáció vagy egy könyvjelzővel vagy anélkül rendelkező lap exportálását. Minden exportálás azonos súlyú. Ha például az exportálási feladat magában foglalja egy 10 oldalból álló jelentés exportálását, és a lekérdezés 70-et ad vissza, az azt jelenti, hogy az API az exportálási feladat 10 oldalából hetet feldolgozott.

Amikor az exportálás befejeződött, a lekérdezési API-hívás egy Power BI URL-címet ad vissza a fájl lekéréséhez. Az URL-cím 24 órán keresztül érhető el.

Támogatott funkciók

Ez a szakasz a következő támogatott funkciók használatát ismerteti:

A nyomtatni kívánt lapok kiválasztása

Adja meg a nyomtatni kívánt lapokat a Lapok lekérése vagy a Lapok lekérése csoport visszatérési értékének megfelelően. Megadhatja az exportált lapok sorrendjét is.

Oldal vagy egyetlen vizualizáció exportálása

Megadhat egy exportálni kívánt lapot vagy vizualizációt. A lapok könyvjelzőkkel vagy anélkül exportálhatók.

Az exportálás típusától függően különböző attribútumokat kell átadnia az ExportReportPage objektumnak. Az alábbi táblázat az egyes exportálási feladatokhoz szükséges attribútumokat határozza meg.

Megjegyzés:

Egyetlen vizualizáció exportálása ugyanolyan súlyú, mint egy oldal exportálása (könyvjelzőkkel vagy anélkül). Ez azt jelenti, hogy a rendszerszámítások szempontjából mindkét művelet ugyanazt az értéket használja.

Attribútum Oldal Egyetlen vizualizáció Megjegyzések
bookmark Választható Does not apply to. Lap exportálása adott állapotban
pageName Applies to. Applies to. Használja a GetPages REST API-t vagy az ügyfél API-tgetPages.
visualName Does not apply to. Applies to. A vizualizáció nevét kétféleképpen lehet lekérni:
  • Használja az getVisuals ügyfél API-t.
  • Figyelje és naplózza a visualClicked eseményt , amely a vizualizáció kiválasztásakor aktiválódik. További információ: Események kezelése
    • .

    Könyvjelzők

    A könyvjelzőkkel egy adott konfigurációban menthet egy jelentést, beleértve az alkalmazott szűrőket és a jelentés vizualizációinak állapotát. Az exportToFile API-val programozott módon exportálhatja egy jelentés könyvjelzőjét, kétféleképpen:

    • Meglévő könyvjelző exportálása

      Meglévő jelentés könyvjelzőjének exportálásához használja az name egyedi (kis- és nagybetűket megkülönböztető) azonosítót, amelyet a JavaScript API könyvjelzőivel szerezhet be.

    • A jelentés állapotának exportálása

      A jelentés aktuális állapotának exportálásához használja a tulajdonságot state . A könyvjelző metódusával bookmarksManager.capture például rögzítheti egy adott felhasználó által a jelentésen végrehajtott módosításokat, majd exportálhatja azt az aktuális állapotában a használatával capturedBookmark.state.

    Megjegyzés:

    A személyes könyvjelzők és az állandó szűrők nem támogatottak.

    Filters

    A PowerBIReportExportConfiguration használatával reportLevelFilters szűrt állapotban exportálhat jelentéseket.

    Szűrt jelentés exportálásához szúrja be a szűrőként használni kívánt URL-lekérdezési sztringparamétereket az ExportFilterbe. A sztring megadásakor el kell távolítania az ?filter= URL-lekérdezési paraméter részét.

    A táblázat néhány szintaxisbeli példát tartalmaz azokra ExportFiltera sztringekre,

    Filter Syntax Példa
    Érték egy mezőben Tábla/mező eq "value" Store/Territory eq 'NC'
    Több érték egy mezőben Tábla/mező a következőben: ('value1', 'value2') Store/Territory in ('NC', 'TN')
    Egy különböző érték egy mezőben, és egy másik mező eltérő értéke Table/Field1 eq 'value1' és Table/Field2 eq 'value2' Store/Territory eq 'NC' és Store/Chain eq 'Fashions Direct'

    Hitelesítés

    Hitelesítést felhasználóval (vagy főfelhasználóval) vagy szolgáltatásnévvel végezhet.

    Sorszintű biztonság (RLS)

    A Sorszintű biztonság (RLS) használatával exportálhat olyan jelentést, amely csak bizonyos felhasználók számára látható adatokat jelenít meg. Ha például regionális szerepkörökkel definiált értékesítési jelentést exportál, programozott módon szűrheti a jelentést, hogy csak egy adott régió jelenjen meg.

    Az RLS használatával történő exportáláshoz a következő engedélyekkel kell rendelkeznie:

    • A jelentéshez csatlakoztatott szemantikai modellre vonatkozó engedélyek írása és újraosztása
    • Annak a munkaterületnek a tagja vagy rendszergazdája, ahol a jelentés található

    Adatvédelem

    A .pdf és a .pptx formátum támogatja a bizalmassági címkéket. Ha egy bizalmassági címkével rendelkező jelentést .pdf-be vagy .pptx-be exportál, az exportált fájl a jelentést annak bizalmassági címkéjével jeleníti meg.

    A bizalmassági címkével rendelkező jelentések nem exportálhatók .pdf-be vagy .pptx fájlba szolgáltatásnévvel.

    Honosítás

    Az exportToFile API használatakor átadhatja a kívánt területi beállításokat. A honosítási beállítások hatással vannak a jelentés megjelenítési módjára, például úgy, hogy a kijelölt helyi formázást módosítják.

    Dinamikus kötés

    Ha egy jelentést úgy szeretne exportálni, hogy az az alapértelmezett szemantikai modellen kívül egy szemantikai modellhez csatlakozik, adja meg a paraméterben a datasetToBind szükséges adathalmaz-azonosítót az API meghívásakor. További információ a dinamikus kötésről.

    Egyidejű kérések

    Az exportToFile API korlátozott számú egyidejű kérést támogat. Az egyidejűleg támogatott kérelmek maximális száma kapacitásonként 500. A korlát túllépésének elkerülése és a túl sok kérés (429) hiba elkerülése érdekében ossza el a terhelést az idő függvényében vagy a kapacitások között. A jelentésnek csak öt oldala van egyszerre feldolgozva. Ha például egy 50 oldalas jelentést exportál, az exportálási feladat 10 egymást követő intervallumban lesz feldolgozva. Az exportálási feladat optimalizálása során érdemes lehet megfontolni néhány feladat párhuzamos végrehajtását.

    Kódpéldák

    Exportálási feladat létrehozásakor négy lépést kell követnie:

    1. Exportálási kérés küldése.
    2. Lekérdezés.
    3. A fájl lekérése.
    4. A fájlstream használata.

    Ez a szakasz példákat tartalmaz az egyes lépésekhez.

    1. lépés – exportálási kérelem küldése

    Az első lépés egy exportálási kérelem küldése. Ebben a példában egy adott lapra vonatkozó exportálási kérelmet küld a rendszer.

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

    2. lépés – lekérdezés

    Az exportálási kérés elküldése után lekérdezéssel állapítsa meg, hogy a várt exportálási fájl mikor áll készen.

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

    3. lépés – a fájl lekérése

    Ha a lekérdezés egy URL-címet ad vissza, használja ezt a példát a fogadott fájl lekéréséhez.

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

    4. lépés – A fájlstream használata

    Ha rendelkezik a fájlstreamel, az igényeinek leginkább megfelelő módon kezelheti. Elküldheti például e-mailben, vagy használhatja az exportált jelentések letöltéséhez.

    Végpontok közötti példa

    Ez egy végpontok közötti példa egy jelentés exportálására. Ez a példa a következő szakaszokat foglalja magában:

    1. Az exportálási kérelem elküldése.
    2. Lekérdezés.
    3. A fájl lekérése.
    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;
    }
}

    Szempontok és korlátozások

    • Az exportálási API-műveletek terhelése lassan futó háttérműveletként van kiértékelve, a Premium-kapacitás terhelésének kiértékelése során leírtak szerint.
    • Az exportált jelentés összes kapcsolódó szemantikai modelljének Prémium vagy Embedded kapacitáson kell lennie, beleértve a Direct Query-kapcsolattal rendelkező szemantikai modelleket is.
    • Az exportált jelentések mérete nem haladhatja meg a 250 MB-ot.
    • A .png-be való exportáláskor a bizalmassági címkék nem támogatottak.
    • Az egyetlen exportált jelentésbe belefoglalható exportálások száma (egyetlen vizualizáció vagy jelentésoldal) 50 (a lapszámozott jelentések exportálását nem beleértve). Ha a kérelem több exportálást tartalmaz, az API hibát ad vissza, és az exportálási feladat megszakad.
    • A Power BI-jelentések fájlba való exportálása nem támogatja a személyes könyvjelzőket és az állandó szűrőket .
    • Az exportToFile API az alapértelmezett értékkel exportálja a jelentést, ha könyvjelzők vagy jelentéslevelszűrők nélkül használják.
    • Az itt felsorolt Power BI-vizualizációk nem támogatottak. A vizualizációkat tartalmazó jelentés exportálásakor a vizualizációkat tartalmazó jelentésrészek nem jelennek meg, és hibaüzenet jelenik meg.
      • Nem hitelesített egyéni Power BI-vizualizációk
      • R-vizualizációk
      • PowerApps
      • Python-vizualizációk
      • Power Automate
      • Többoldalas jelentésvizualizáció
      • Visio
      • ArcGIS-vizualizációk

    Kapcsolódó tartalom

    Tekintse át, hogyan ágyazhat be tartalmakat az ügyfelek és a szervezet számára:

    További kérdések? Próbálja ki a Power BI-közösség