Exportovanie stránkovanej zostavy do súboru

Článok
05/23/2024

Rozhranie exportToFile API umožňuje exportovať stránkovanú zostavu Power BI pomocou volania REST. Podporované sú nasledujúce formáty súborov:

.pptx (PowerPoint)
.pdf (a accessible PDF, or PDF/UA)
.xlsx (Excel)
.docx (Word)
.Csv
.Xml
.Mhtml
Obrázok
Pri exporte na obrázok nastavte formát obrázka pomocou nastavenia formátu OutputFormat . Podporované OutputFormat hodnoty sú:
- .tiff (predvolené)
- .Bmp
- .Emf
- .gif
- .jpeg
- .png

Príklady používania

Funkciu exportu môžete použiť rôznymi spôsobmi. Tu je niekoľko príkladov:

Tlačidlo odoslania na tlač – v aplikácii vytvorte tlačidlo, kliknutím na ktoré sa spustí úloha exportu. Úloha môže exportovať zobrazenú zostavu ako .pdf alebo .pptx. Po dokončení môže používateľ súbor prijať ako stiahnutie. Pomocou parametrov zostavy a nastavení formátu môžete exportovať zostavu v konkrétnom stave vrátane filtrovaných údajov, vlastných veľkostí strán a ďalších nastavení špecifických formátom. Keďže rozhranie API je asynchrónne, môže to nejaký čas trvať, kým bude súbor k dispozícii.
Príloha e-mailu – odosielajte automatizované e-maily v nastavených intervaloch s priloženou zostavou vo formáte .pdf. Tento scenár môže byť užitočný, ak chcete automatizovať odosielanie týždennej zostavy vedúcim pracovníkom.

Používanie rozhrania API

Požiadavky na licencie

Exportovaná zostava sa musí nachádzať v pracovnom priestore podporovanom kapacitou Premium, Embedded alebo Fabric.
Rozhranie exportToFile API má obmedzenú podporu v službe Premium na používateľa.

Udalosti vykresľovania

Ak chcete zabezpečiť, že export sa nezačína skôr, než sa vizuál dokončí vykresľovanie, použite rozhranie API udalostí "Vykresľovanie" a export sa spustí až po dokončení vykresľovania.

Volebných

Rozhranie API je asynchrónne. Pri volaní rozhrania API exportToFile sa spustí úloha exportu. Po spustení úlohy exportu použite vzorkovanie na sledovanie úlohy, kým nebude dokončená.

Po dokončení exportu volanie rozhrania API vzorkovania vráti URL adresu služby Power BI na získanie súboru. URL adresa je k dispozícii 24 hodín.

Podporované funkcie

Nastavenia formátu

Zadajte rôzne nastavenia formátu pre každý formát súboru. Podporované vlastnosti a hodnoty zodpovedajú parametrom informácií o zariadení pre parametre URL stránkovanej zostavy.

Tu sú dva príklady. Prvý sa používa na export prvých štyroch strán zostavy pomocou veľkosti strany zostavy do súboru .pptx. Druhým príkladom je export tretej strany zostavy do súboru .jpeg.

Exportovanie prvých štyroch strán do formátu .pptx

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

Exportovanie tretej strany do formátu .jpeg

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

Parametre zostavy

Rozhranie API môžete použiť exportToFile na exportovanie zostavy pomocou programovania s množinou parametrov zostavy. Vykonáva sa to pomocou možností parametrov zostavy.

Tu je príklad nastavenia hodnôt parametrov zostavy.

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

Overovanie

Overovanie môžete vykonať pomocou používateľa (alebo hlavného používateľa) alebo objektu služby.

Zabezpečenie na úrovni riadkov

Pri používaní sémantického modelu služby Power BI, ktorý má ako zdroj údajov definované zabezpečenie na úrovni riadkov (RLS), môžete exportovať zostavu zobrazujúcu údaje, ktoré sú viditeľné len pre určitých používateľov. Ak napríklad exportujete zostavu predaja, ktorá je definovaná s rolami pre oblasti, môžete naprogramovať filtrovanie zostavy tak, aby sa zobrazila len určitá oblasť.

Ak chcete exportovať pomocou zabezpečenia na úrovni riadkov, musíte si prečítať povolenie pre sémantický model služby Power BI, ktorý zostava používa ako zdroj údajov.

Tu je príklad použitia platného mena používateľa na zabezpečenie na úrovni riadkov (RLS).

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

Jediné prihlásenie – SQL a Dataverse (SSO)

V službe Power BI máte možnosť nastaviť OAuth s jediného prihlásenia. Keď tak urobíte, poverenia pre používateľa, ktorý si zobrazuje zostavu, sa použijú na načítanie údajov. Prístupový token v hlavičke požiadavky sa nepoužíva na prístup k údajom. Token sa musí odovzdať s efektívnou identitou v tele príspevku.

Získanie správneho prístupového tokenu pre zdroj, ku ktorému chcete získať prístup, môže byť niekedy zložité.

V prípade Azure SQL je https://database.windows.netzdrojom .
V prípade funkcie Dataverse je https:// prostriedkom adresa vášho prostredia. Napríklad, https://contoso.crm.dynamics.com.

Prístup k rozhraniu API tokenu pomocou metódy AuthenticationContext.AcquireTokenAsync .

Tu je príklad na poskytnutie efektívnej identity (mena používateľa) pomocou prístupového tokenu.

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

Súbežné žiadosti

Funkcia exportToFile podporuje obmedzený počet súbežných požiadaviek. Maximálny počet súbežných požiadaviek na vykreslenie stránkovanej zostavy je 500. Ak sa chcete vyhnúť prekročeniu limitu a výskytu chyby Too Many Requests (429), rozmiestnite zaťaženie v čase alebo v rámci kapacít.

So službou Premium na používateľa (PPU) exportToFileumožňuje rozhranie API len jednu požiadavku v päťminútovom okne. Viaceré požiadavky v rámci päťminútového okna majú za následok chybu s príponou Too Many Requests (Príliš veľa požiadaviek ) (429).

Príklady kódu

Súpravu rozhranie API služby Power BI SDK použitú v príkladoch kódu je možné stiahnuť tu.

Pri vytváraní úlohy exportu postupujte podľa troch krokov:

Odoslanie žiadosti o export.
Volebných.
Načítajte súbor.

Táto časť obsahuje príklady každého kroku.

Krok 1 – odoslanie žiadosti o export

Prvým krokom je odoslanie žiadosti o export. V tomto príklade sa odošle žiadosť o export konkrétneho rozsahu strán, veľkosti a hodnôt parametrov zostavy.

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

Krok 2 – vzorkovanie

Po odoslaní žiadosti o export použite vzorkovanie a identifikujte, kedy bude čakajúci exportovaný súbor pripravený.

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

Krok 3 – na získanie súboru

Keď vzorkovanie vráti URL adresu, prijatý súbor môžete načítať pomocou tohto príkladu.

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

Komplexný príklad

Toto je komplexný príklad exportu zostavy. Tento príklad obsahuje tieto fázy:

Odoslanie žiadosti o export.
Vzorkovanie.
Načítajte súbor.

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

Dôležité informácie a obmedzenia

Export stránkovanej zostavy, ktorá má ako zdroj údajov sémantický model služby Power BI, nie je v týchto prípadoch podporovaný:
- Volajúci je profil objektu služby.
- Jeden zo zdrojov údajov sémantického modelu je nakonfigurovaný so zapnutým jediným prihlásením (SSO) a bola zadaná efektívna identita.
- Sémantický model služby Power BI obsahuje DirectQuery pre Azure Analysis Services alebo iný sémantický model služby Power BI a bola zadaná efektívna identita.
Export stránkovanej zostavy, ktorá má zdroj údajov služby Azure Analysis Services nakonfigurovaný s povoleným jediným prihlásením (SSO), nie je podporovaný v týchto prípadoch:
- Volajúci je profil objektu služby.
- Volajúci je hlavný používateľ a bola poskytnutá efektívna identita.
Ak chcete exportovať stránkovanú zostavu s efektívnou identitou, meno používateľa musí byť existujúcim používateľom z ID Microsoft Entra vášho nájomníka.
Export zostavy je obmedzený na 60 minút, čo zodpovedá životu prístupového tokenu používateľa. Ak sa pri exportovaní veľkého množstva údajov vyskytne chyba s uplynutím časového limitu 60 minút, zvážte zníženie množstva údajov pomocou vhodných filtrov.
Hypertextové prepojenie URL adresy na zdieľanie súborov (cesta k zdieľaniu súboru /UNC) nefunguje pri exportovaní publikovanej stránkovanej zostavy v služba Power BI online.

Získajte ďalšie informácie o vkladaní obsahu pre zákazníkov a organizáciu:

Zdieľať cez

Exportovanie stránkovanej zostavy do súboru

Príklady používania

Používanie rozhrania API

Požiadavky na licencie

Udalosti vykresľovania

Volebných

Podporované funkcie

Nastavenia formátu

Exportovanie prvých štyroch strán do formátu .pptx

Exportovanie tretej strany do formátu .jpeg

Parametre zostavy

Overovanie

Zabezpečenie na úrovni riadkov

Jediné prihlásenie – SQL a Dataverse (SSO)

Súbežné žiadosti

Príklady kódu

Krok 1 – odoslanie žiadosti o export

Krok 2 – vzorkovanie

Krok 3 – na získanie súboru

Komplexný príklad

Dôležité informácie a obmedzenia

Pripomienky

Ďalšie zdroje informácií

Zdieľať cez

Exportovanie stránkovanej zostavy do súboru

Príklady používania

Používanie rozhrania API

Požiadavky na licencie

Udalosti vykresľovania

Volebných

Podporované funkcie

Nastavenia formátu

Exportovanie prvých štyroch strán do formátu .pptx

Exportovanie tretej strany do formátu .jpeg

Parametre zostavy

Overovanie

Zabezpečenie na úrovni riadkov

Jediné prihlásenie – SQL a Dataverse (SSO)

Súbežné žiadosti

Príklady kódu

Krok 1 – odoslanie žiadosti o export

Krok 2 – vzorkovanie

Krok 3 – na získanie súboru

Komplexný príklad

Dôležité informácie a obmedzenia

Súvisiaci obsah

Pripomienky

Ďalšie zdroje informácií