Sdílet prostřednictvím

Exportovat stránkovanou sestavu do souboru

  • Článek

Rozhraní API exportToFile umožňuje exportovat stránkovanou sestavu Power BI pomocí volání REST. Podporují se následující formáty souborů:

  • .pptx (PowerPoint)

  • .pdf (a přístupné PDF nebo PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .csv

  • .xml

  • .mhtml

  • obrázku
    Při exportu do obrázku nastavte formát obrázku pomocí nastavení formátu OutputFormat. Podporované OutputFormat hodnoty jsou:

    • .tiff (výchozí)
    • .bmp
    • .emf
    • .gif
    • .jpeg
    • .png

Příklady použití

Funkci exportu můžete použít různými způsoby. Tady je několik příkladů:

  • tlačítko Odeslat k tisku – V aplikaci vytvořte tlačítko, které po kliknutí na aktivuje úlohu exportu. Úloha může exportovat zobrazenou sestavu jako .pdf nebo .pptx. Po dokončení může uživatel soubor přijmout jako stažení. Pomocí parametrů sestavy a nastavení formátu můžete sestavu exportovat do určitého stavu, včetně filtrovaných dat, vlastních velikostí stránek a dalších nastavení specifických pro formát. Vzhledem k tomu, že rozhraní API je asynchronní, může nějakou dobu trvat, než bude soubor k dispozici.

  • Příloha e-mailu – Automatizovaný e-mail se odesílá v nastavených intervalech s příloženou zprávou .pdf. Tento scénář může být užitečný, pokud chcete automatizovat odesílání týdenních sestav vedoucím pracovníkům.

Použití rozhraní API

Licenční požadavky

  • Sestava, kterou exportujete, se musí nacházet v pracovním prostoru s podporou kapacity Premium, Embedded nebo Fabric.
  • Rozhraní API exportToFile má omezenou podporu v Premium na uživatele (PPU).

Vykreslování událostí

Abyste měli jistotu, že export nezačne před dokončením vykreslování vizuálu, použijte rozhraní API událostí vykreslování a export zahajte pouze po dokončení vykreslování.

Hlasování

Rozhraní API je asynchronní. Když se volá exportToFile API, aktivuje úlohu exportu. Po aktivaci úlohy exportu použijte dotazování ke sledování úlohy, dokud není dokončena.

Po dokončení exportu volání rozhraní API pro dotazování vrátí adresu URL Power BI pro získání souboru. Adresa URL je k dispozici po dobu 24 hodin.

Podporované funkce

Nastavení formátu

Zadejte různá nastavení formátu pro každý formát souboru. Podporované vlastnosti a hodnoty jsou ekvivalentní parametrům Informace o zařízení pro parametry adresy URL stránkované sestavy.

Tady jsou dva příklady. První krok je export prvních čtyř stránek sestavy ve velikosti stránky sestavy do souboru .pptx. Druhým příkladem je export třetí stránky sestavy do .jpeg souboru.

Export prvních čtyř stránek do .pptx

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

Export třetí stránky do .jpeg

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

Parametry sestavy

Můžete použít rozhraní API exportToFile pro programové exportování sestavy se sadou parametrů sestavy. Provádí se to využitím schopností parametru sestavy.

Tady je příklad nastavení hodnot parametrů sestavy.

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

Autentizace

Můžete se ověřit pomocí uživatele (nebo hlavního uživatele) nebo instančního objektu.

Zabezpečení na úrovni řádků (RLS)

Při použití sémantického modelu Power BI, který má definované zabezpečení na úrovni řádků (RLS) jako zdroj dat, můžete exportovat sestavu zobrazující data, která jsou viditelná jenom určitým uživatelům. Pokud například exportujete sestavu prodeje definovanou s regionálními rolemi, můžete sestavu programově filtrovat tak, aby se zobrazila jenom určitá oblast.

Pokud chcete exportovat pomocí zabezpečení na úrovni řádků (RLS), musíte mít oprávnění ke čtení pro sémantický model Power BI, který se používá jako zdroj dat pro sestavu.

Zde je příklad vytvoření efektivního uživatelského jména pro Row-Level Security (RLS).

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

Jednotné přihlašování SQL a Dataverse (SSO)

V Power BI máte možnost nastavit OAuth s jednotným přihlašováním. Když to uděláte, přihlašovací údaje pro uživatele, který sestavu zobrazuje, se použijí k načtení dat. Přístupový token v hlavičce požadavku se nepoužívá pro přístup k datům. Token musí být předán s účinnou identitou v těle zprávy.

Získání správného přístupového tokenu pro prostředek, ke kterému chcete získat přístup, může být někdy složité.

  • V případě Azure SQL je prostředek https://database.windows.net.
  • Pro Dataverse je zdrojem adresa https:// vašeho prostředí. Například https://contoso.crm.dynamics.com.

Získejte přístup k rozhraní API tokenu pomocí metody AuthenticationContext.AcquireTokenAsync.

Tady je příklad pro zadání efektivní identity (uživatelského jména) pomocí pří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"
         }
        }
     ]
   }
}

Souběžné požadavky

exportToFile podporuje omezený počet souběžných požadavků. Maximální počet souběžných požadavků na vykreslení stránkované sestavy je 500. Pokud se chcete vyhnout překročení limitu a získání chyby Příliš mnoho požadavků (429), distribuujte zatížení v průběhu času nebo napříč kapacitami.

Služba Premium na uživatele (PPU)umožňuje rozhraní API exportToFile pouze jeden požadavek v pětiminutovém intervalu. Více požadavků v pětiminutovém okně způsobí chybu Příliš mnoho požadavků (429).

Příklady kódu

Sada Power BI API SDK používaná v příkladech kódu může být stažena zde.

Při vytváření úlohy exportu je potřeba provést tři kroky:

  1. Odeslání žádosti o export
  2. Hlasování.
  3. Načítá se soubor.

Tato část obsahuje příklady pro každý krok.

Krok 1 – odeslání žádosti o export

Prvním krokem je odeslání žádosti o export. V tomto příkladu se odešle požadavek na export pro konkrétní rozsah stránek, velikost a hodnoty parametrů sestavy.

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 – dotazování

Po odeslání žádosti o export použijte dotazování, abyste zjistili, kdy je soubor exportu, na který čekáte, připravený.

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 – získání souboru

Jakmile dotazování vrátí adresu URL, použijte tento příklad k získání přijatého souboru.

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

Kompletní příklad

Toto je kompletní příklad pro export sestavy. Tento příklad zahrnuje následující fáze:

  1. Odeslání žádosti o export.
  2. Dotazování.
  3. Získání souboru.
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é informace a omezení

  • Export stránkované sestavy, která má jako zdroj dat sémantický model Power BI, se nepodporuje v následujících případech:

    • Volající je profil hlavní služby .
    • Jeden ze zdrojů dat sémantického modelu je nakonfigurovaný s povoleným jednotným přihlašováním (SSO) a byla zadána efektivní identita.
    • Sémantický model Power BI má DirectQuery k Azure Analysis Services nebo k jinému sémantickému modelu Power BI a byla poskytnuta efektivní identita.

  • Export stránkované sestavy, která má zdroj dat služby Azure Analysis Services nakonfigurovaný s povoleným jednotným přihlašováním, se nepodporuje v následujících případech:

    • Volající je instančním profilem služebního principála .
    • Volající je hlavní uživatel a byla poskytována efektivní identita.

  • Chcete-li exportovat stránkovanou sestavu s platnou identitou, musí být uživatelské jméno existujícím uživatelem v Microsoft Entra ID vašeho tenanta.

  • Export sestavy je omezený na 60 minut, což odpovídá životnosti přístupového tokenu uživatele. Pokud při exportu velkých objemů dat dojde k chybě vypršení časového limitu po překročení hranice 60 minut, zvažte snížení množství dat pomocí vhodných filtrů.

  • Hyperlink URL sdíleného souboru (cesta sdílené složky /UNC) při exportu publikované stránkované sestavy do služby Power BI Online nefunguje.

Související obsah

Přečtěte si, jak vložit obsah pro vaše zákazníky a vaši organizaci: