Power BI -raportin vieminen tiedostoon

Artikkeli
03/23/2023
9 minuutin lukuaika

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

.pptx (PowerPoint)
.pdf
.png
- Kun viet .png, useita sivuja sisältävä raportti pakataan .zip tiedostoksi
- Jokainen .zip-paketin tiedosto edustaa yhtä raportin sivua
- Sivujen nimet ovat samat kuin Hae sivuja- tai Hae sivuja ryhmästä -ohjelmointirajapintojen palautusarvot

Käyttöesimerkit

Voit käyttää vientitoimintoa 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. Kun se 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, jossa on liitteenä .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

Järjestelmänvalvojan asetukset

Varmista ennen ohjelmointirajapinnan käyttämistä, että seuraavat järjestelmänvalvojan vuokraajan 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 visualisoinnin hahmontamista, käytä Tapahtumien hahmontaminen -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 osoittaa valmiin työn määrän. 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 on käsitellyt 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 seuraavien tuettujen ominaisuuksien käyttö:

Tulostettavien sivujen valitseminen
Sivun tai yksittäisen visualisoinnin vieminen
Kirjanmerkit
Suodattimet
Todentaminen
Rivitason suojaus (RLS)
Tietojen suojaus
Lokalisointi
Dynaaminen sidonta

Tulostettavien sivujen valitseminen

Määritä ne 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ääritteet ExportReportPage-objektiin . Alla olevassa taulukossa on määritetty, mitkä määritteet vaaditaan kuhunkin vientityöhön.

Huomautus

Yksittäisen visualisoinnin viemisellä on sama painoarvo kuin sivun viemisellä (kirjanmerkkien kanssa tai ilman sitä). Tämä tarkoittaa sitä, että järjestelmän laskutoimituksissa molemmilla toiminnoilla on sama arvo.

Määrite	sivu	Kommentit
`bookmark`	Valinnainen	Vie sivu tietyssä tilassa -toiminnolla
`pageName`		Käytä GetPages REST -ohjelmointirajapintaa tai `getPages` asiakkaan ohjelmointirajapintaa.
`visualName`		Saat visualisoinnin nimen kahdella tavalla: Käytä asiakkaan ohjelmointirajapintaa`getVisuals`. Kuuntele ja kirjaa visualClicked-tapahtuma , joka käynnistyy, kun visualisointi valitaan. Lisätietoja on artikkelissa Tapahtumien käsitteleminen .

Kirjanmerkit

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

Vie olemassa oleva kirjanmerkki

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

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

Huomautus

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

Suodattimet

Kun käytät reportLevelFilters-ominaisuutta kohdassa PowerBIReportExportConfiguration, voit viedä raportin suodatetussa tilassa.

Vie suodatettu raportti lisäämällä ne URL-osoitteen kyselymerkkijonoparametrit, joita haluat käyttää suodattimena, ExportFilter-kohtaan. Kun lisäät merkkijonon, sinun on poistettava URL-kyselyparametrin ?filter=-osa.

Alla olevassa taulukossa on muutamia syntaksiesimerkkejä merkkijonoista, jotka voit välittää kohteeseen ExportFilter.

Suodata	Syntax	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 vain käyttäjän (tai pääkäyttäjän) tai palvelun päänimen.

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ä myyntiraporttia, joka on määritetty alueellisten roolien perusteella, voit suodattaa raportin ohjelmallisesti niin, että vain tietty alue näytetään.

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

Kirjoitus- ja uudelleenjakamisoikeudet siihen tietojoukkoon, 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 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 sijainnin mukaan.

Dynaaminen sidonta

Jos haluat viedä raportin, kun se on yhdistetty toiseen tietojoukkoon, määritä vaadittu tietojoukon tunnus parametrissa datasetToBind API:a kutsuttaessa. Lue lisää dynaamisesta sidonnasta.

Samanaikaiset pyynnöt

- exportToFile ohjelmointirajapinta tukee samanaikaisia vientityöpyyntöjä. Alla olevassa taulukossa näkyy niiden töiden määrä, jotka voidaan suorittaa samanaikaisesti sen mukaan, missä SKU:ssa raportti sijaitsee. Samanaikaiset pyynnöt viittaavat raporttisivuihin. Esimerkiksi yhden vientipyynnön 55 sivua A4-varastointiyksikössä käsitellään samanaikaisesti. Tämä prosessi kestää suunnilleen yhtä kauan kuin 55 vientipyynnön lähettäminen yhdellä sivulla.

Työ, joka ylittää samanaikaisten pyyntöjen määrän, ei pääty. Jos esimerkiksi viet 30 sivua A2-SKU:ssa, ensimmäiset 25 työpaikkaa suoritetaan, ja loput viisi odottavat seuraavaa suoritusjaksoa.

Vain viisi raportin sivua käsitellään samanaikaisesti. Jos esimerkiksi viet raportin, jossa on 50 sivua, vientityö käsitellään kymmenen peräkkäisen välein. Vientityön optimoinnissa kannattaa ehkä harkita muutamien töiden suorittamista rinnakkain. Jos sinulla on esimerkiksi A1-varastointiyksikkö, jonka enimmäiskäsittelyrajoitus on 20 samanaikaista sivua vientiä kohden, voit käsitellä neljä 50 sivun raporttia samanaikaisesti. Vain viisi sivua kustakin työstä käsitellään tiettynä ajankohtana. Tämän seurauksena neljän työn kokonaisaika on lyhyempi kuin koko raportin vieminen yhdessä työssä.

Huomautus

Power BI -raportin vientiä tiedostoon exportToFile-ohjelmointirajapinnan avulla ei tueta käyttäjäkohtaisessa Premiumissa (PPU).
Sivutettujen raporttien samanaikaisten raporttien enimmäisraja on erilainen, ja sitä käsitellään artikkelissa Sivutetun raportin vieminen tiedostoon.

Azure-SKU	Office-SKU	Samanaikaisten raporttisivujen enimmäismäärä
A1	EM1	20
A2	EM2	25
A3	EM3	35
A4	P1	55
A5	P2	95
A6	P3	175
A7¹	P4¹	200
A8¹	P5¹	200

¹ SKU, joka on suurempi kuin 100 Gt, ei ole saatavilla kaikilla alueilla. Jos haluat pyytää näiden varastointiyksiköiden käyttöä alueilla, joilla ne eivät ole käytettävissä, ota yhteyttä Microsoft-tilin hallintaan.

Koodiesimerkit

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

Vientipyynnön lähettäminen.
Kysely.
Tiedoston noutaminen.
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äytettävissä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 prosessista

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

Vientipyynnön lähettäminen.
Kysely.
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 hitaana taustatoimintona, joka on kuvattu artikkelissa Premium-kapasiteetin kuormituksen arviointi.
Vietävän raportin on sijaittava Premium- tai Embedded-kapasiteetissa.
Kaikkien vietävän raportin liittyvien tietojoukkojen on sijaittava Premium- tai Embedded-kapasiteetissa, mukaan lukien tietojoukot, joilla on DirectQuery-yhteys.
Vietyjen raporttien tiedostokoko ei voi olla yli 250 Mt.
Luottamuksellisuustunnisteita ei tueta .png vietäessä.
Yksittäiseen vietyön raporttiin voi sisällyttää 50 vientiä (yksittäisiä visualisointeja tai raporttisivuja), joita ei sisällytetä sivutettujen raporttien vientiin. Jos pyyntöön sisältyy enemmän vientiä, ohjelmointirajapinta palauttaa virheen ja vientityö peruutetaan.
Henkilökohtaisia kirjanmerkkejä ja pysyviä suodattimia ei tueta.
Power BI -raportin viemistä tiedostoon ohjelmointirajapinnan exportToFile avulla ei tueta käyttäjäkohtaisessa Premiumissa (PPU).
Alla lueteltuja Power BI -visualisointeja ei tueta. Kun viet raportin, joka sisältää nämä visualisoinnit, raportin osia, jotka sisältävät nämä visualisoinnit, 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

Seuraavat vaiheet

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

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

Power BI -raportin vieminen tiedostoon

Käyttöesimerkit

Ohjelmointirajapinnan käyttäminen

Järjestelmänvalvojan asetukset

Tapahtumien hahmontaminen

Polling

Tuetut ominaisuudet

Tulostettavien sivujen valitseminen

Sivun tai yksittäisen visualisoinnin vieminen

Kirjanmerkit

Suodattimet

Todentaminen

Rivitason suojaus (RLS)

Tietojen suojaus

Lokalisointi

Dynaaminen sidonta

Samanaikaiset pyynnöt

Koodiesimerkit

Vaihe 1 – vientipyynnön lähettäminen

Vaihe 2 – kysely

Vaihe 3 – tiedoston noutaminen

Vaihe 4 – tiedostovirran käyttäminen

Esimerkki koko prosessista

Huomioitavat asiat ja rajoitukset

Seuraavat vaiheet

Lisäresursseja

Lisäresursseja