Jaa

Sivutetun raportin vieminen tiedostoon

  • Artikkeli

exportToFile-ohjelmointirajapinnan avulla voit viedä Power BI:n sivutetun raportin REST-kutsun avulla. Seuraavia tiedostomuotoja tuetaan:

  • .pptx (PowerPoint)

  • .pdf (ja Helppokäyttöinen PDF tai PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .csv

  • .xml

  • .mhtml-

  • Kuvan
    Kun viet kuvaa, määritä kuvan muoto OutputFormat-asetuksella. Tuetut OutputFormat arvot ovat seuraavat:

    • .tiff (oletus)
    • .bmp
    • .emf
    • .gif
    • .jpeg
    • .png

Käyttöesimerkkejä

Voit käyttää vientiominaisuutta eri tavoin. Tässä on pari esimerkkiä:

  • Lähetä tulostukseen - – 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. Raporttiparametrien ja muotoasetusten avulla voit viedä raportin tietyssä tilassa (mukaan lukien suodatetut tiedot, mukautetut sivukoot ja muut muotokohtaiset asetukset). Koska ohjelmointirajapinta on asynkroninen, saattaa kestää jonkin aikaa, ennen kuin tiedosto on käytettävissä.

  • Sähköpostin liitetiedosto -: lähetä automatisoitu sähköpostiviesti määritetyin väliajoin käyttäen liitettyä .pdf raporttia. Tästä skenaariosta voi olla hyötyä, jos haluat automatisoida viikkoraportin lähettämisen johtoportaalle.

Ohjelmointirajapinnan käyttäminen

Käyttöoikeusvaatimukset

  • Vietävän raportin on sijaittava työtilassa, jota tukee Premium-, Embedded- tai Fabric-kapasiteetti.
  • exportToFile -ohjelmointirajapinnalla on rajoitettu tuki käyttäjäkohtaisen Premiumin (PPU) .

Tapahtumien hahmontaminen

Jos haluat varmistaa, että vienti ei ala ennen visualisoinnin hahmontamista, käytä "Hahmontaminen" -tapahtumien ohjelmointirajapinnan ja aloita vienti vain, 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.

Kun vienti on valmis, kyselyn ohjelmointirajapintakutsu palauttaa Power BI:n URL-osoitteen, tiedoston noutamista varten. URL-osoite on käytettävissä 24 tunnin ajan.

Tuetut ominaisuudet

Muotoiluasetukset

Määritä eri muotoiluasetukset kullekin tiedostomuodolle. Tuetut ominaisuudet ja arvot vastaavat sivutetun raportin URL-parametrien laitetietojen parametrien.

Tässä on kaksi esimerkkiä. Ensimmäinen on tarkoitettu raportin neljän ensimmäisen sivun viemiseen raporttisivun koon avulla .pptx-tiedostoon. Toinen esimerkki on raportin kolmannen sivun vieminen .jpeg tiedostoon.

Neljän ensimmäisen sivun vieminen .pptx

{
      "format": "PPTX",
      "paginatedReportConfiguration":{
            "formatSettings":{
                  "UseReportPageSize": "true",
                  "StartPage": "1",
                  "EndPage": "4"
            }
      }
}

Kolmannen sivun vieminen .jpeg

{
      "format": "IMAGE",
      "paginatedReportConfiguration":{
            "formatSettings":{
                  "OutputFormat": "JPEG",
                  "StartPage": "3",
                  "EndPage": "3"
            }
      }
}

Raporttiparametrit

exportToFile ohjelmointirajapinnan avulla voit viedä raportin ohjelmallisesti raporttiparametrien avulla. Tämä tehdään käyttämällä raporttiparametrin ominaisuuksia.

Tässä on esimerkki raporttiparametrien arvojen määrittämisestä.

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "parameterValues":[
                  {"name": "State", "value": "WA"},
                  {"name": "City", "value": "Seattle"},
                  {"name": "City", "value": "Bellevue"},
                  {"name": "City", "value": "Redmond"}
            ]
      }
}

Todennus

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

Rivitason suojaus (RLS)

Kun käytät semanttista Power BI -mallia, jonka tietolähteeksi on määritetty rivitason suojaus, 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ä rivitason suojauksen avulla, sinulla on oltava lukuoikeudet siihen Power BI:n semanttiseen malliin, jota raportti käyttää tietolähteenä.

Tässä on esimerkki rivitason suojauksen käytössä olevan käyttäjänimen lisäämisestä.

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "identities": [
                  {"username": "john@contoso.com"}
            ]
      }
}

Kertakirjautuminen SQL ja Dataverse (SSO)

Power BI:ssä voit halutessasi määrittää OAuth-todennusta kertakirjautumisen avulla. Tällöin tietoja noudetaan raporttia tarkastelevan käyttäjän tunnistetiedoilla. Pyynnön otsikon käyttöoikeustietuetta ei käytetä tietojen käyttämiseen. Tunnus on välitettävä post-leipätekstin voimassa olevan identiteetin kanssa.

Joskus oikean käyttöoikeustietueen saaminen resurssille, jota haluat käyttää, voi olla hankalaa.

  • Azure SQL:ssä resurssi on https://database.windows.net.
  • Dataversen tapauksessa resurssi on ympäristösi https:// osoite. Esimerkiksi https://contoso.crm.dynamics.com.

Käytä tunnuksen ohjelmointirajapintaa AuthenticationContext.AcquireTokenAsync -menetelmällä.

Tässä on esimerkki voimassa olevan käyttäjätiedon (käyttäjänimen) ja käyttöoikeustietueen toimittamisesta.

{
       "format":"PDF",
       "paginatedReportConfiguration":{
          "formatSettings":{
             "AccessiblePDF":"true",
             "PageHeight":"11in",
             "PageWidth":"8.5in",
             "MarginBottom":"2in"
          },
          "identities":[
             {
                "username":"john@contoso.com",
                "identityBlob": {
                "value": "eyJ0eX....full access token"
         }
        }
     ]
   }
}

Samanaikaiset pyynnöt

exportToFile tukee rajoitettua määrää samanaikaisia pyyntöjä. Samanaikaisten sivutettujen raporttien hahmontamispyyntöjen suurin sallittu määrä on 500. Jotta vältetään rajan ylittäminen ja liian monta pyyntöä (429) -virheen saaminen joko ajan kuluessa tai kapasiteeteissa olevan kuormituksen jakamiseksi.

Käyttäjäkohtaisen Premiumin (PPU) exportToFile-ohjelmointirajapinta sallii vain yhden yhden pyynnön viiden minuutin aikana. Useat pyynnöt viiden minuutin ikkunassa aiheuttavat Liian monta pyyntöä (429) -virheen.

Koodiesimerkkejä

Koodiesimerkeissä käytettävä Power BI -ohjelmointirajapinnan SDK on ladattavissa täältä.

Kun luot vientityön, nopeutettavaa on kolme vaihetta:

  1. Vientipyynnön lähettäminen.
  2. Kysely.
  3. Tiedoston noutaminen.

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 tietylle sivualueelle, koolle ja raporttiparametriarvoille.

private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId)
{
    // For documentation purposes the export configuration is created in this method
    // Ordinarily, it would be created outside and passed in
    var paginatedReportExportConfiguration = new PaginatedReportExportConfiguration()
    {
        FormatSettings = new Dictionary<string, string>()
        {
            {"PageHeight", "14in"},
            {"PageWidth", "8.5in" },
            {"StartPage", "1"},
            {"EndPage", "4"},
        },
        ParameterValues = new List<ParameterValue>()
        {
            { new ParameterValue() {Name = "State", Value = "WA"} },
            { new ParameterValue() {Name = "City", Value = "Redmond"} },
        },
    };

    var exportRequest = new ExportReportRequest
    {
        Format = FileFormat.PDF,
        PaginatedReportExportConfiguration = paginatedReportExportConfiguration,
    };

    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<Export> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the ExportToAsync response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations
            return null;
        }

        var httpMessage = 
            await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
            
        exportStatus = httpMessage.Body;
        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 only populated when the status is either Running or NotStarted
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;

            await Task.Delay(retryAfterInSec * secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return exportStatus;
}

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 GetExportStatusAsync response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        var httpMessage = 
            await Client.Reports.GetFileOfExportToFileInGroupWithHttpMessagesAsync(groupId, reportId, export.Id);

        return new ExportedFile
        {
            FileStream = httpMessage.Body,
            ReportName = export.ReportName,
            FileExtension = export.ResourceFileExtension,
        };
    }

    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string ReportName;
    public string FileExtension;
}

Esimerkki koko lopusta

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

  1. Vientipyynnön lähettäminen.
  2. Polling.
  3. Tiedoston hakeminen.
private async Task<ExportedFile> ExportPaginatedReport(
    Guid reportId,
    Guid groupId,
    int pollingtimeOutInMinutes,
    CancellationToken token)
{
    try
    {
        var exportId = await PostExportRequest(reportId, groupId);

        var export = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
        if (export == null || export.Status != ExportState.Succeeded)
        {
           // Error, failure in exporting the report
            return null;
        }

        return await GetExportedFile(reportId, groupId, export);
    }
    catch
    {
        // Error handling
        throw;
    }
}

Huomioitavat asiat ja rajoitukset

  • Sellaisen sivutetun raportin viemistä, jonka tietolähteenä on Power BI:n semanttinen malli, ei tueta seuraavissa tapauksissa:

    • Soittaja on palvelun pääprofiilin.
    • Yksi semanttisen mallin tietolähteistä on määritetty kertakirjautumisella (SSO) käyttöön ja annettiin voimassa olevat käyttäjätiedot.
    • Semanttisessa Power BI -mallissa on DirectQuery Azure Analysis Servicesiin tai muuhun semanttiseen Power BI -malliin, ja käytössä olevat käyttäjätiedot on annettu.

  • Sellaisen sivutetun raportin viemistä, jossa Azure Analysis Services -tietolähde on määritetty kertakirjautumisen (SSO) avulla, ei tueta seuraavissa tapauksissa:

    • Soittaja on palvelun pääprofiilin.
    • Soittaja on pääkäyttäjä, ja käytössä olevat käyttäjätiedot on annettu.

  • Jotta käyttäjänimi voi viedä sivutetun raportin, jossa on käytössä olevat käyttäjätiedot, käyttäjänimen on oltava olemassa oleva käyttäjä vuokraajasi Microsoft Entra -tunnuksella.

  • Raportin vienti on rajoitettu 60 minuuttiin, joka vastaa käyttäjän käyttöoikeustietueen käyttöikää. Jos saat aikakatkaisuvirheen yli 60 minuutin merkinnän, kun viet suuria tietomääriä, harkitse tietojen määrän pienentämistä asianmukaisten suodattimien avulla.

  • Tiedoston jaetun URL-osoitteen hyperlinkki (tiedoston jakaminen /UNC-polku) ei toimi, kun julkaistu sivutettu raportti viedään Power BI -palvelusta verkossa.

Aiheeseen liittyvä sisältö

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