Power BI -raportin vieminen tiedostoon

- 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 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. 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 exportToFile ei 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 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.

Kysely

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
• Sivun tai yksittäisen visualisoinnin vieminen
• Kirjanmerkit
• Suodattimet
• Todennus
• Rivitason suojaus (RLS)
• Tietosuoja
• Lokalisointi
• Dynaaminen sidonta

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		Käytä tätä sivun viemiseen tietyssä tilassa
pageName			Käytä GetPages REST -ohjelmointirajapintaa tai getPages asiakkaan ohjelmointirajapintaa.
visualName			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.

Suodata	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:

• Kirjoitusoikeudet siihen semanttiseen malliin, johon raportti on yhdistetty
• Sen työtilan, jossa raportti sijaitsee, osallistuja tai järjestelmänvalvoja

Tietojen suojaus

.pdf ja .pptx tukevat luottamuksellisuustunnisteita. Jos viet luottamuksellisuustunnisteen sisältävän raportin .pdf tai .pptx, 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 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.
• Luottamuksellisuustunnisteita ei tueta .png vietäessä.
• 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.
• Sellaisen Power BI -raportin viemistä, joka on yhdistetty vähintään yhteen semanttiseen yhdistelmämalliin ja jossa on vähintään yksi ulkoinen tietolähde kertakirjautuminen (SSO) käytössä, ei tueta. Visualisoinnit eivät ehkä hahmonna oikein vietäessä.
• 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

Liittyvä sisältö

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

• Sivutetun raportin vieminen tiedostoon
• Upottaminen asiakkaillesi
• Upottaminen organisaatiollesi
• Power BI -raportin vieminen ja lähettäminen sähköpostitse Power Automatella

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