Sivutetun raportin vieminen tiedostoon

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

• .pptx (PowerPoint)

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

• .xlsx (Excel)

• .docx (Word)

• .Csv

• .Xml

• .Mhtml

• Kuva
  Kun viet kuvaa, määritä kuvan muoto muotoiluasetuksella OutputFormat . Tuettuja OutputFormat arvoja 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 -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. 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 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.

Ohjelmointirajapinnan käyttäminen

Lisenssivaatimukset

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

Tapahtumien hahmontaminen

Jos haluat varmistaa, että vienti ei ala ennen kuin visualisointi on hahmontanut, 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.

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

Muotoiluasetukset

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

Seuraavssa 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-tiedostoon

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

Kolmannen sivun vieminen .jpeg-muotoon

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

Raporttiparametrit

-ohjelmointirajapinnan exportToFile avulla voit viedä raportin ohjelmallisesti käyttäen raporttiparametreja. Tämä tehdään raporttiparametrien toiminnoilla.

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"}
            ]
      }
}

Todentaminen

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

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 https:// ympäristösi osoite. Esimerkki: 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ä. Sivutettujen raporttien hahmontamispyyntöjen samanaikainen enimmäismää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äkohtaisessa exportToFilePremiumissa ohjelmointirajapinta sallii vain 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. Polling.
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. Kyselyjä.
3. Tiedoston noutaminen.

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ääprofiili.
  • 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ääprofiili.
  • 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 julkaistua sivutettua raporttia viedään Power BI -palvelu online-tilassa.

Liittyvä sisältö

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

• Raportin vieminen tiedostoon
• Upottaminen asiakkaillesi
• Upottaminen organisaatiollesi