Sdílet prostřednictvím

Export stránkované sestavy do souboru

  • Článek

Rozhraní exportToFile API 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ázek
    Při exportu do obrázku nastavte formát obrázku OutputFormat pomocí nastavení formátu. 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 soubor .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 je rozhraní API asynchronní, může být soubor k dispozici až po určité době.

  • Příloha e-mailu – v nastavených intervalech pošlete automatizovaný e-mail s připojenou sestavou .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

Požadavky na licenci

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í.

cyklické dotazování

Rozhraní API je asynchronní. Při volání rozhraní API exportToFile aktivuje úlohu exportu. Po aktivaci úlohy exportu můžete pomocí dotazování sledovat úlohu, dokud se nedokončí.

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ím je export prvních čtyř stránek sestavy pomocí velikosti stránky sestavy do souboru .pptx. Druhým příkladem je export třetí stránky sestavy do souboru .jpeg.

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

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

Export třetí stránky do souboru .jpeg

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

Parametry sestavy

Rozhraní API můžete použít exportToFile k programovému exportu sestavy se sadou parametrů sestavy. To se provádí pomocí funkcí 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"}
            ]
      }
}

Ověřování

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ů, musíte mít oprávnění ke čtení pro sémantický model Power BI, který sestava používá jako zdroj dat.

Tady je příklad zadání efektivního uživatelského jména pro zabezpečení na úrovni řádků.

{
      "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 efektivní identitou v těle příspěvku.

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 https://database.windows.netprostředek .
  • Pro Dataverse je https:// prostředek adresou vašeho prostředí. Například https://contoso.crm.dynamics.com.

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

Podporuje exportToFile omezený počet souběžných požadavků. Maximální počet souběžných žádostí o 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.

V případě premium na uživatele (PPU) exportToFilerozhraní API umožňuje v pětiminutovém intervalu jenom jeden požadavek. Více požadavků v pětiminutovém okně způsobí chybu Příliš mnoho požadavků (429).

Příklady kódu

Sadu API Power BI SDK použitou v příkladech kódu si můžete stáhnout zde.

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

  1. Odeslání žádosti o export
  2. Dotazová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. Načítá se soubor.
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;
    }
}

Úvahy 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 instančního objektu.
    • 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 do služby Azure Analysis Services nebo do jiného sémantického modelu Power BI a byla poskytována 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 profil instančního objektu.
    • Volající je hlavní uživatel a byla poskytována efektivní identita.

  • Pokud chcete exportovat stránkovanou sestavu s efektivní identitou, musí být uživatelské jméno existujícím uživatelem z ID Microsoft Entra 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ě časového limitu za 60minutovou značku, zvažte snížení množství dat pomocí vhodných filtrů.

  • Hypertextový odkaz URL sdílené složky (cesta /UNC) nefunguje při exportu publikované stránkované sestavy na služba Power BI online.

Související obsah

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