Lapszámozott jelentés exportálása fájlba

  • Cikk

Az exportToFile API REST-hívással teszi lehetővé a többoldalas Power BI-jelentések exportálását. A következő fájlformátumok támogatottak:

  • .pptx (PowerPoint)

  • .pdf (és akadálymentes PDF vagy PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .Csv

  • .Xml

  • .Mhtml

  • Rendszerkép
    Képre való exportáláskor állítsa be a képformátumot a OutputFormat formátumbeállításon keresztül. A támogatott OutputFormat értékek a következők:

    • .tiff (alapértelmezett)
    • .Bmp
    • .Emf
    • .gif
    • .jpeg
    • .png

Felhasználási példák

Az exportálási funkciót többféleképpen is használhatja. Íme néhány példa:

  • Küldés nyomtatásra gomb – Az alkalmazásban hozzon létre egy gombot, amelyre kattintva egy exportálási feladat aktiválódik. A feladat exportálhatja a megtekintett jelentést .pdf vagy .pptx formátumban. Ha elkészült, a felhasználó letöltheti a fájlt. Jelentésparaméterek és formátumbeállítások használatával a jelentést egy adott állapotban exportálhatja, beleértve a szűrt adatokat, az egyéni oldalméreteket és más formátumspecifikus beállításokat. Mivel az API aszinkron, hosszabb időt is igénybe vehet, amíg a fájl elérhetővé válik.

  • E-mail melléklet – Automatikus e-mail küldése megadott időközönként, csatolt .pdf jelentéssel. Ez a forgatókönyv akkor lehet hasznos, ha egy heti jelentést szeretne automatizálni a vezetőknek.

Az API használata

License requirements

  • Az exportált jelentésnek egy Prémium, Embedded vagy Fabric kapacitással rendelkező munkaterületen kell lennie.
  • Az exportToFile API korlátozott támogatást nyújt a Felhasználónkénti Premium (PPU)-ban.

Események megjelenítése

Annak érdekében, hogy az exportálás ne kezdődjön a vizualizáció renderelésének befejezése előtt, használja a "Rendering" events API-t , és csak a renderelés befejezésekor kezdje el az exportálást.

ciklikus lekérdezések

Az API aszinkron. Az exportToFile API meghívásakor egy exportálási feladatot aktivál. Az exportálási feladat aktiválása után a lekérdezéssel nyomon követheti a feladatot, amíg be nem fejeződik.

Amikor az exportálás befejeződött, a lekérdezési API-hívás egy Power BI URL-címet ad vissza a fájl lekéréséhez. Az URL-cím 24 órán keresztül érhető el.

Támogatott funkciók

Formázási beállítások

Adjon meg különböző formátumbeállításokat az egyes fájlformátumokhoz. A támogatott tulajdonságok és értékek egyenértékűek a lapszámozott jelentés URL-paramétereinek Eszközadatok paramétereivel .

Bemutatunk két példát. Az első egy jelentés első négy oldalának exportálása a jelentés oldalméretével egy .pptx fájlba. A második példa egy jelentés harmadik oldalának exportálása .jpeg fájlba.

Az első négy oldal exportálása .pptx fájlba

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

A harmadik oldal exportálása .jpeg fájlba

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

Jelentésparaméterek

Az exportToFile API-val programozott módon exportálhat egy jelentést jelentésparaméterek készletével. Ez a jelentésparaméter képességeinek használatával történik.

Íme egy példa a jelentésparaméter-értékek beállítására.

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

Hitelesítés

Hitelesítést felhasználóval (vagy főfelhasználóval) vagy szolgáltatásnévvel végezhet.

Sorszintű biztonság (RLS)

Ha olyan Power BI szemantikai modellt használ, amelynek sorszintű biztonsága (RLS) adatforrásként van definiálva, exportálhat olyan jelentést, amely csak bizonyos felhasználók számára látható adatokat jelenít meg. Ha például regionális szerepkörökkel definiált értékesítési jelentést exportál, programozott módon szűrheti a jelentést, hogy csak egy adott régió jelenjen meg.

Az RLS használatával történő exportáláshoz olvasási engedéllyel kell rendelkeznie ahhoz a Power BI szemantikai modellhez, amelyet a jelentés adatforrásként használ.

Íme egy példa egy hatékony felhasználónév megadására az RLS-hez.

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

Egyszeri bejelentkezéses SQL és Dataverse (SSO)

A Power BI-ban lehetősége van az OAuth SSO-val való beállítására. Ha így tesz, a jelentést megtekintő felhasználó hitelesítő adatait használja az adatok lekérésére. A kérelem fejlécében lévő hozzáférési jogkivonat nem az adatok elérésére szolgál. A jogkivonatot a post törzsben lévő érvényes identitással kell átadni.

A elérni kívánt erőforrás megfelelő hozzáférési jogkivonatának beszerzése néha nehézkes lehet.

  • Az Azure SQL esetében az erőforrás a https://database.windows.netkövetkező: .
  • A Dataverse esetében az erőforrás a https:// környezet címe. For example, https://contoso.crm.dynamics.com.

A token API elérése az AuthenticationContext.AcquireTokenAsync metódussal.

Íme egy példa egy érvényes identitás (felhasználónév) hozzáférési jogkivonattal való megadására.

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

Egyidejű kérések

Az exportToFile egyidejű kérések száma korlátozott. Az egyidejű lapszámozott jelentésmegjelenítési kérelmek maximális száma 500. A korlát túllépésének elkerülése és a túl sok kérés (429) hiba elkerülése érdekében ossza el a terhelést az idő függvényében vagy a kapacitások között.

A Premium Per User (PPU) használatával az exportToFile API mindössze egy kérést engedélyez egy ötperces ablakban. Az ötperces ablakban több kérés túl sok kérést (429) eredményez.

Kódpéldák

A példakódokban használt Power BI API SDK innen tölthető le.

Exportálási feladat létrehozásakor három lépést kell követnie:

  1. Exportálási kérés küldése.
  2. Szavazó.
  3. A fájl lekérése.

Ez a szakasz példákat tartalmaz az egyes lépésekhez.

1. lépés – exportálási kérelem küldése

Az első lépés egy exportálási kérelem küldése. Ebben a példában egy adott oldaltartományra, méretre és jelentésparaméter-értékre vonatkozó exportálási kérelmet küld a rendszer.

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

2. lépés – lekérdezés

Miután elküldte az exportálási kérelmet, lekérdezéssel állapítsa meg, hogy a várt exportálási fájl mikor áll készen.

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

3. lépés – a fájl lekérése

Ha a lekérdezés egy URL-címet ad vissza, használja ezt a példát a fogadott fájl lekéréséhez.

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

Végpontok közötti példa

Ez egy végpontok közötti példa egy jelentés exportálására. Ez a példa a következő szakaszokat foglalja magában:

  1. Az exportálási kérelem elküldése.
  2. Lekérdezés.
  3. A fájl lekérése.
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;
    }
}

Szempontok és korlátozások

  • A power BI szemantikai modellel rendelkező lapszámozott jelentések adatforrásként való exportálása a következő esetekben nem támogatott:

    • A hívó egy egyszerű szolgáltatásprofil.
    • A szemantikai modell egyik adatforrása az egyszeri bejelentkezés (SSO) engedélyezésével van konfigurálva, és egy hatékony identitás lett megadva.
    • A Power BI szemantikai modell rendelkezik DirectQueryvel az Azure Analysis Serviceshez vagy egy másik Power BI szemantikai modellhez, és hatékony identitást biztosított.

  • A lapszámozott jelentések exportálása, amelyeken engedélyezve van az Egyszeri bejelentkezés (SSO) beállítással konfigurált Azure Analysis Services-adatforrás, az alábbi esetekben nem támogatott:

  • Ha érvényes identitással szeretne többoldalas jelentést exportálni, a felhasználónévnek meglévő felhasználónak kell lennie a bérlő Microsoft Entra-azonosítójából.

  • A jelentés exportálása legfeljebb 60 perc lehet, amely megfelel a felhasználói hozzáférési jogkivonat élettartamának. Ha időtúllépési hibát kap a 60 perces jelnél nagyobb mennyiségű adat exportálásakor, fontolja meg az adatok mennyiségének csökkentését a megfelelő szűrők használatával.

  • A fájlmegosztás URL-hivatkozása (fájlmegosztás /UNC elérési út) nem működik, ha közzétett lapszámozott jelentést exportál Power BI szolgáltatás online.

Kapcsolódó tartalom

Tekintse át, hogyan ágyazhat be tartalmakat az ügyfelek és a szervezet számára: