Power BI -raportin vieminen tiedostoon

- exportToFile ohjelmointirajapinta mahdollistaa Power BI -raportin viemisen REST-kutsun avulla. Seuraavia tiedostomuotoja tuetaan:

  • .pptx (PowerPoint)
  • .Pdf
  • .png
    • Kun viet tiedoston .png-tiedostoon, useita sivuja sisältävä raportti pakataan .zip-tiedostoksi
    • Jokainen .zip-tiedoston tiedosto edustaa yhtä raporttisivua
    • Sivujen nimet ovat samat kuin Hae sivuja- tai Hae sivuja ryhmästä -ohjelmointirajapintojen palautusarvot

Muistiinpano

Power BI -raportin viemistä tiedostoon exportToFile-ohjelmointirajapinnan avulla ei tueta käyttäjäkohtaisessa Premiumissa (PPU).

Käyttöesimerkkejä

Voit käyttää vientiominaisuutta useilla tavoilla. Tässä on pari esimerkkiä:

  • Lähetä tulostukseen -painike – Luo sovelluksessa painike, joka käynnistää napsautettaessa vientityön. Työ voi viedä tarkastellun raportin .pdf- tai .pptx-muodossa. Kun asennus on valmis, käyttäjä voi vastaanottaa tiedoston latauksena. Kirjanmerkkien avulla voit viedä raportin tietyssä tilassa, mukaan lukien määritetyt suodattimet, osittajat ja muut asetukset. Koska ohjelmointirajapinta on asynkroninen, saattaa kestää jonkin aikaa, ennen kuin tiedosto on käytettävissä.

  • Sähköpostin liite : lähetä määritetyin väliajoin automatisoitu sähköpostiviesti, johon on liitetty .pdf-raportti. Tästä skenaariosta voi olla hyötyä, jos haluat automatisoida viikkoraportin lähettämisen johtoportaalle. Lisätietoja on artikkelissa Power BI -raportin vieminen ja lähettäminen sähköpostitse Power Automatella

Ohjelmointirajapinnan käyttäminen

Lisenssivaatimukset

  • Vietävän raportin on sijaittava työtilassa, jota tukee Premium-, Embedded- tai Fabric-kapasiteetti.
  • Ohjelmointirajapintaa exportToFileei tueta käyttäjäkohtaisessa Premiumissa (PPU).

Järjestelmänvalvojan asetukset

Varmista ennen ohjelmointirajapinnan käyttöä, että seuraavat järjestelmänvalvojan vuokraaja-asetukset ovat käytössä:

  • Vie raportit PowerPoint-esityksinä tai PDF-tiedostoina – oletusarvoisesti käytössä.
  • Vie raportit kuvatiedostoina – Pakollinen vain .png-tiedostoille ja oletusarvoisesti poissa käytöstä.

Tapahtumien hahmontaminen

Sen varmistamiseksi, että vienti ei ala ennen kuin visualisointi on valmis, käytä Hahmontaminen-tapahtumien ohjelmointirajapintaa ja aloita vienti vasta, kun hahmontaminen on valmis.

Polling

Ohjelmointirajapinta on asynkroninen. Kun exportToFile-ohjelmointirajapintaa kutsutaan, vientityö käynnistyy. Kun vientityö on käynnistetty, voit seurata työtä kyselyllä , kunnes työ on valmis.

Kyselyn aikana ohjelmointirajapinta palauttaa luvun, joka edustaa valmiin työn määrää. Kunkin vientityön työmäärä lasketaan työn viennin kokonaismäärän perusteella. Vientiin kuuluu yksittäisen visualisoinnin tai sivun vieminen kirjanmerkkien kanssa tai ilman sitä. Kaikilla viennillä on sama painoarvo. Jos vientityösi sisältää esimerkiksi kymmenen sivua sisältävän raportin viemisen ja kysely palauttaa arvon 70, ohjelmointirajapinta käsittelee seitsemän vientityön kymmenestä sivusta.

Kun vienti on valmis, kyselyn ohjelmointirajapintakutsu palauttaa Power BI URL -osoitteen, josta tiedoston voi noutaa. URL-osoite on käytettävissä 24 tunnin ajan.

Tuetut ominaisuudet

Tässä osiossa kuvataan, miten voit käyttää seuraavia tuettuja ominaisuuksia:

Tulostettavan sivun valitseminen

Määritä sivut, jotka haluat tulostaa Hae sivuja- tai Hae sivuja ryhmästä -palautusarvon mukaan. Voit myös määrittää vietävien sivujen järjestyksen.

Sivun tai yksittäisen visualisoinnin vieminen

Voit määrittää vietävän sivun tai yksittäisen visualisoinnin. Sivuja voidaan viedä kirjanmerkkien kanssa tai ilman niitä.

Vientityypistä riippuen sinun on välitettävä eri määritteitä ExportReportPage-objektiin. Seuraavassa taulukossa on määritetty, mitkä määritteet kunkin vientityön kohdalla vaaditaan.

Muistiinpano

Yksittäisen visualisoinnin viemisellä on sama painoarvo kuin sivun viemisellä (kirjanmerkkien kanssa tai ilman). Tämä tarkoittaa sitä, että järjestelmän laskutoimitusten osalta kummallakin operaatiolla on sama arvo.

Määrite Sivu Yksittäinen visualisointi Kommentit
bookmark Valinnainen Does not apply to. Käytä tätä sivun viemiseen tietyssä tilassa
pageName Applies to. Applies to. Käytä GetPages REST -ohjelmointirajapintaa tai getPages asiakkaan ohjelmointirajapintaa.
visualName Does not apply to. Applies to. Saat visualisoinnin nimen kahdella tavalla:
  • Käytä asiakkaan ohjelmointirajapintaagetVisuals.
  • Kuuntele ja kirjaa visualisointiSlicked-tapahtuma , joka käynnistyy, kun visualisointi valitaan. Lisätietoja on ohjeaiheessa Tapahtumien käsitteleminen.
  • .

    Kirjanmerkit

    Kirjanmerkkien avulla raportti voidaan tallentaa tiettyyn kokoonpanoon, mukaan lukien käytössä olevat suodattimet ja raportin visualisointien tila. ExportToFile-ohjelmointirajapinnan avulla voit viedä raportin kirjanmerkin ohjelmallisesti kahdella tavalla:

    • Vie olemassa oleva kirjanmerkki

      Jos haluat viedä aiemmin luodun raportin kirjanmerkin, käytä - name ominaisuutta. Saat sen yksilöllisen (kirjainkoko on merkitsevä) tunnuksen käyttämällä kirjanmerkkien JavaScript-ohjelmointirajapintaa.

    • Vie raportin tila

      Jos haluat viedä raportin nykyisen tilan, käytä -ominaisuutta state . Voit esimerkiksi kirjanmerkin -menetelmän avulla tallentaa tietyn käyttäjän raporttiin bookmarksManager.capture tekemät muutokset ja viedä sen sitten nykyisessä tilassa :n avulla capturedBookmark.state.

    Muistiinpano

    Henkilökohtaisia kirjanmerkkejä ja pysyviä suodattimia ei tueta.

    Suodattimet

    Kun käytät -toimintoa reportLevelFilters kohdassa PowerBIReportExportConfiguration, voit viedä raportin suodatoidussa tilassa.

    Jos haluat viedä suodatetun raportin, lisää suodattimena käytettävät URL-osoitteen kyselymerkkijonoparametrit ExportFilter-kohtaan. Kun kirjoitat merkkijonon, sinun on poistettava ?filter= URL-kyselyparametrin -osa.

    Taulukko sisältää muutamia syntaksiesimerkkejä merkkijonoista, jotka voit välittää kohteeseen ExportFilter.

    Suodatus Syntaksi Esimerkki
    Kentän arvo Table/Field eq 'value' Store/Territory eq 'NC'
    Useita kentän arvoja Table/Field in ('value1', 'value2') Store/Territory in ('NC', 'TN')
    Erillinen arvo yhdessä kentässä ja eri erillinen arvo toisessa kentässä Table/Field1 eq 'value1' and Table/Field2 eq 'value2' Store/Territory eq 'NC' and Store/Chain eq 'Fashions Direct'

    Todentaminen

    Voit todentaa palvelun käyttäjän (tai pääkäyttäjän ) tai palvelun päänimen avulla.

    Rivitason suojaus (RLS)

    Rivitason suojauksen (RLS) avulla voit viedä raportin, jossa näkyy vain tietyille käyttäjille näkyviä tietoja. Jos olet esimerkiksi viemässä aluerooleilla määritettyä myyntiraporttia, voit suodattaa raportin ohjelmallisesti niin, että vain tietty alue näkyy.

    Jos haluat viedä RLS:n avulla, sinulla on oltava seuraavat oikeudet:

    • Kirjoitus- ja uudelleenjakamisoikeudet siihen semanttiseen malliin, johon raportti on yhdistetty
    • Sen työtilan jäsen tai järjestelmänvalvoja, jossa raportti sijaitsee

    Tietojen suojaus

    .pdf- ja .pptx-muodot tukevat luottamuksellisuustunnisteita. Jos viet luottamuksellisuustunnisteen sisältävän raportin .pdf- tai .pptx-tiedostoon, viety tiedosto näyttää raportin luottamuksellisuustunnisteineen.

    Luottamuksellisuustunnisteella merkittyä raporttia ei voi viedä .pdf- tai .pptx-tiedostoon palvelun päänimen avulla.

    Lokalisointi

    Kun käytät ohjelmointirajapintaa exportToFile , voit valita haluamasi aluekohtaiset asetukset. Lokalisointiasetukset vaikuttavat siihen, miten raportti näytetään, esimerkiksi muuttamalla muotoilun valitun kieliasetuksen mukaan.

    Dynaaminen sidonta

    Jos haluat viedä raportin, kun se on yhdistetty semanttiseen malliin, toinen on semanttinen oletusmalli, määritä vaadittu tietojoukon datasetToBind tunnus parametrissa ohjelmointirajapintaa kutsuttaessa. Lue lisätietoja dynaamisesta sidonnasta.

    Samanaikaiset pyynnöt

    - exportToFile ohjelmointirajapinta tukee rajoitettua määrää samanaikaisia pyyntöjä. Tuettujen samanaikaisten pyyntöjen enimmäismäärä on 500 kapasiteettia kohden. Jotta vältetään rajan ylittäminen ja liian monta pyyntöä (429) -virheen saaminen joko ajan kuluessa tai kapasiteeteissa olevan kuormituksen jakamiseksi. Vain viisi raportin sivua käsitellään samanaikaisesti. Jos esimerkiksi olet viemässä raporttia, jossa on 50 sivua, vientityö käsitellään kymmenen peräkkäisen välein. Vientityön optimoinnissa kannattaa ehkä harkita parin työn suorittamista rinnakkain.

    Koodiesimerkkejä

    Kun luot vientityön, sinun on suoritettava neljä vaihetta:

    1. Vientipyynnön lähettäminen.
    2. Kyselyjä.
    3. Tiedoston noutaminen.
    4. Tiedostojen suoratoiston käyttäminen.

    Tässä osiossa annetaan esimerkkejä jokaisesta vaiheesta.

    Vaihe 1 – vientipyynnön lähettäminen

    Ensimmäinen vaihe on vientipyynnön lähettäminen. Tässä esimerkissä vientipyyntö lähetetään tietystä sivusta.

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

    Vaihe 2 – kysely

    Kun olet lähettänyt vientipyynnön, määritä kyselyn avulla, milloin se vientitiedosto on valmis, jota odotat.

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

    Vaihe 3 – tiedoston noutaminen

    Kun kysely palauttaa URL-osoitteen, nouda vastaanotetut tiedostot tämän esimerkin avulla.

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

    Vaihe 4 – Tiedostovirran käyttäminen

    Kun käytössäsi on tiedostovirta, voit käsitellä sitä parhaiten tarpeisiisi sopivalla tavalla. Voit esimerkiksi lähettää sen sähköpostitse tai ladata viedyt raportit sen avulla.

    Esimerkki koko lopusta

    Tämä on esimerkki raportin koko vientimallista. Tämä esimerkki sisältää seuraavat vaiheet:

    1. Vientipyynnön lähettäminen.
    2. Kyselyjä.
    3. Tiedoston noutaminen.
    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;
        }
    }
    

    Huomioitavat asiat ja rajoitukset

    • Vienti-ohjelmointirajapinnan toiminnon kuormitus arvioidaan hitaaksi taustatoiminnoksi, joka on kuvattu kohdassa Premium-kapasiteetin kuormituksen arviointi.
    • Kaikkien vietävän raportin semanttisten mallien on sijaittava Premium- tai Embedded-kapasiteetissa, mukaan lukien semanttiset mallit, joilla on DirectQuery-yhteys.
    • Vietyjen raporttien tiedostokoko ei voi olla yli 250 Mt.
    • Kun viet .png-tiedostoon, luottamuksellisuustunnisteita ei tueta.
    • Yksittäiseen vietyihin raportteihin sisällytettävien vientien (yksittäiset visualisoinnit tai raporttisivut) määrä on 50 (lukuun ottamatta sivutettujen raporttien vientiä). Jos pyyntö sisältää enemmän vientiä, ohjelmointirajapinta palauttaa virheen ja vientityö peruutetaan.
    • Henkilökohtaisia kirjanmerkkejä ja pysyviä suodattimia ei tueta, kun Power BI -raportti viedään tiedostoon.
    • -ohjelmointirajapinta exportToFile vie raportin oletusarvolla, jos sitä käytetään ilman kirjanmerkkejä tai raporttiaLevelFilters.
    • Tässä lueteltuja Power BI -visualisointeja ei tueta. Kun viet raportin, joka sisältää nämä visualisoinnit, näitä visualisointeja sisältäviä raportin osia ei hahmonneta, ja ne näyttävät virhesymbolin.
      • Sertifioimattomat Power BI:n mukautetut visualisoinnit
      • R-visualisoinnit
      • PowerApps
      • Python-visualisoinnit
      • Power Automate
      • Sivutetun raportin visualisointi
      • Visio
      • ArcGIS-visualisoinnit

    Katso, miten voit upottaa sisältöä asiakkaille ja organisaatiolle:

    Onko sinulla kysyttävää? Kokeile Power BI -yhteisö