Εξαγωγή σελιδοποιημένης αναφοράς σε αρχείο

  • Άρθρο

Το exportToFile API επιτρέπει την εξαγωγή μιας σελιδοποιημένης αναφοράς Power BI με χρήση μιας κλήσης REST. Υποστηρίζονται οι ακόλουθες μορφές αρχείων:

  • .pptx (PowerPoint)

  • .pdf (και Accessible PDF ή PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .Csv

  • .Xml

  • .Mhtml

  • Image
    Κατά την εξαγωγή σε μια εικόνα, ορίστε τη μορφή εικόνας μέσω της ρύθμισης OutputFormat μορφοποίησης. Οι υποστηριζόμενες OutputFormat τιμές είναι:

    • .tiff (προεπιλογή)
    • .Bmp
    • .Emf
    • .gif
    • .jpeg
    • .png

Παραδείγματα χρήσης

Μπορείτε να χρησιμοποιήσετε τη δυνατότητα εξαγωγής με διάφορους τρόπους. Δείτε μερικά παραδείγματα:

  • Κουμπί αποστολής για εκτύπωση - Στην εφαρμογή σας, δημιουργήστε ένα κουμπί που θα ενεργοποιεί μια εργασία εξαγωγής. Η εργασία μπορεί να εξαγάγει την προβολευμένη αναφορά ως .pdf ή .pptx. Όταν ολοκληρωθεί, ο χρήστης μπορεί να λάβει το αρχείο ως λήψη. Χρησιμοποιώντας τις παραμέτρους αναφοράς και τις ρυθμίσεις μορφοποίησης, μπορείτε να εξαγάγετε την αναφορά σε μια συγκεκριμένη κατάσταση, συμπεριλαμβανομένων των φιλτραρισμένων δεδομένων, των προσαρμοσμένων μεγεθών σελίδας και άλλων ρυθμίσεων για συγκεκριμένη μορφή. Καθώς το API είναι ασύγχρονο, μπορεί να χρειαστεί λίγος χρόνος για να γίνει διαθέσιμο το αρχείο.

  • Συνημμένο ηλεκτρονικού ταχυδρομείου - Στείλτε ένα αυτοματοποιημένο μήνυμα ηλεκτρονικού ταχυδρομείου σε καθορισμένα διαστήματα, με μια συνημμένη αναφορά .pdf. Αυτό το σενάριο μπορεί να είναι χρήσιμο αν θέλετε να αυτοματοποιήσετε την αποστολή μιας εβδομαδιαίας αναφοράς στα στελέχη.

Χρήση του API

Απαιτήσεις άδειας χρήσης

Απόδοση συμβάντων

Για να βεβαιωθείτε ότι η εξαγωγή δεν ξεκινά πριν ολοκληρωθεί η απόδοση της απεικόνισης, χρησιμοποιήστε το API συμβάντων "Απόδοση" και ξεκινήστε την εξαγωγή μόνο όταν ολοκληρωθεί η απόδοση.

Σταθμοσκόπησης

Το API είναι ασύγχρονο. Όταν καλείται το API exportToFile , ενεργοποιεί μια εργασία εξαγωγής. Μετά την ενεργοποίηση μιας εργασίας εξαγωγής, χρησιμοποιήστε την ανίχνευση για να παρακολουθήσετε την εργασία, μέχρι να ολοκληρωθεί.

Όταν ολοκληρωθεί η εξαγωγή, η κλήση ανίχνευσης API επιστρέφει μια διεύθυνση URL Power BI για τη λήψη του αρχείου. Η διεύθυνση URL είναι διαθέσιμη για 24 ώρες.

Υποστηριζόμενες δυνατότητες

Ρυθμίσεις μορφοποίησης

Καθορίστε διάφορες ρυθμίσεις μορφοποίησης για κάθε μορφή αρχείου. Οι υποστηριζόμενες ιδιότητες και τιμές είναι ισοδύναμες με τις παραμέτρους πληροφοριών συσκευής για τις παραμέτρους διεύθυνσης URL σελιδοποιημένης αναφοράς.

Ακολουθούν δύο παραδείγματα. Η πρώτη αφορά την εξαγωγή των πρώτων τεσσάρων σελίδων μιας αναφοράς χρησιμοποιώντας το μέγεθος της σελίδας αναφοράς σε ένα αρχείο .pptx. Το δεύτερο παράδειγμα αφορά την εξαγωγή της τρίτης σελίδας μιας αναφοράς σε ένα αρχείο .jpeg.

Εξαγωγή των πρώτων τεσσάρων σελίδων σε ένα .pptx

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

Εξαγωγή της τρίτης σελίδας σε ένα αρχείο .jpeg

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

Παράμετροι αναφοράς

Μπορείτε να χρησιμοποιήσετε το exportToFile API για να εξαγάγετε μια αναφορά μέσω προγραμματισμού με ένα σύνολο παραμέτρων αναφοράς. Αυτό γίνεται με χρήση των δυνατοτήτων παραμέτρων αναφοράς.

Ακολουθεί ένα παράδειγμα για τον ορισμό τιμών παραμέτρων αναφοράς.

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

Έλεγχος ταυτότητας

Μπορείτε να κάνετε έλεγχο ταυτότητας χρησιμοποιώντας έναν χρήστη (ή κύριο χρήστη) ή μια κύρια υπηρεσία.

Ασφάλεια σε επίπεδο γραμμών (RLS)

Όταν χρησιμοποιείτε ένα σημασιολογικό μοντέλο Power BI στο οποίο έχει οριστεί ασφάλεια σε επίπεδο γραμμών (RLS) ως προέλευση δεδομένων, μπορείτε να εξαγάγετε μια αναφορά που εμφανίζει δεδομένα που είναι ορατά μόνο σε ορισμένους χρήστες. Για παράδειγμα, εάν εξάγετε μια αναφορά πωλήσεων που έχει οριστεί με τοπικούς ρόλους, μπορείτε να φιλτράρετε την αναφορά μέσω προγραμματισμού έτσι ώστε να εμφανίζεται μόνο μία συγκεκριμένη περιοχή.

Για εξαγωγή με χρήση RLS, πρέπει να έχετε δικαίωμα ανάγνωσης για το σημασιολογικό μοντέλο Power BI που χρησιμοποιεί η αναφορά ως προέλευση δεδομένων.

Ακολουθεί ένα παράδειγμα παροχής ενός αποτελεσματικού ονόματος χρήστη για το RLS.

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

SQL καθολικής σύνδεσης και Dataverse (SSO)

Στο Power BI, έχετε την επιλογή να ορίσετε OAuth με SSO. Όταν το κάνετε αυτό, τα διαπιστευτήρια για τον χρήστη που προβάλλει την αναφορά χρησιμοποιούνται για την ανάκτηση δεδομένων. Το διακριτικό πρόσβασης στην κεφαλίδα αίτησης δεν χρησιμοποιείται για πρόσβαση στα δεδομένα. Το διακριτικό πρέπει να μεταβιβαστεί με την ουσιαστική ταυτότητα στο σώμα δημοσίευσης.

Η λήψη του σωστού διακριτικού πρόσβασης για τον πόρο στον οποίο θέλετε να αποκτήσετε πρόσβαση μπορεί ορισμένες φορές να είναι δύσκολη.

  • Για το Azure SQL, ο πόρος είναι https://database.windows.net.
  • Για το Dataverse, ο πόρος είναι η διεύθυνση για το https:// περιβάλλον σας. Για παράδειγμα, https://contoso.crm.dynamics.com.

Αποκτήστε πρόσβαση στο API διακριτικού χρησιμοποιώντας τη μέθοδο AuthenticationContext.AcquireTokenAsync .

Ακολουθεί ένα παράδειγμα για την παροχή μιας αποτελεσματικής ταυτότητας (όνομα χρήστη) με διακριτικό πρόσβασης.

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

Ταυτόχρονες αιτήσεις

Η exportToFile υποστηρίζει έναν περιορισμένο αριθμό ταυτόχρονων αιτήσεων. Ο μέγιστος αριθμός ταυτόχρονων αιτήσεων απόδοσης σελιδοποιημένης αναφοράς είναι 500. Για να αποφύγετε την υπέρβαση του ορίου και να ισχύει ένα σφάλμα Πάρα πολλές αιτήσεις (429), είτε διανείμετε το φορτίο σε βάθος χρόνου, είτε σε σύνολα εκχωρημένων πόρων.

Με το Premium ανά χρήστη (PPU), το exportToFile API επιτρέπει μόνο μία αίτηση σε ένα παράθυρο πέντε λεπτών. Πολλές αιτήσεις μέσα στο παράθυρο των πέντε λεπτών έχουν ως αποτέλεσμα ένα σφάλμα Πάρα πολλές αιτήσεις (429).

Παραδείγματα κώδικα

Μπορείτε να κάνετε λήψη του Power BI API SDK που χρησιμοποιείται στα παραδείγματα κώδικα εδώ.

Όταν δημιουργείτε μια εργασία εξαγωγής, υπάρχουν τρία βήματα που πρέπει να ακολουθήσετε:

  1. Αποστολή αίτησης εξαγωγής.
  2. Σταθμοσκόπησης.
  3. Λήψη του αρχείου.

Αυτή η ενότητα παρέχει παραδείγματα για κάθε βήμα.

Βήμα 1 - Αποστολή αίτησης εξαγωγής

Το πρώτο βήμα είναι η αποστολή μιας αίτησης εξαγωγής. Σε αυτό το παράδειγμα, αποστέλλεται μια αίτηση εξαγωγής για μια συγκεκριμένη περιοχή σελίδων, μέγεθος και τιμές παραμέτρων αναφοράς.

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 - Ανίχνευση

Αφού αποστείλετε μια αίτηση εξαγωγής, χρησιμοποιήστε την ανίχνευση για να προσδιορίσετε πότε θα είναι έτοιμο το αρχείο εξαγωγής που περιμένετε.

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 - Λήψη του αρχείου

Όταν η ανίχνευση επιστρέψει μια διεύθυνση URL, χρησιμοποιήστε αυτό το παράδειγμα για να λάβετε το αρχείο που λάβατε.

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

Αναλυτικό παράδειγμα

Αυτό είναι ένα τελικό παράδειγμα για την εξαγωγή μιας αναφοράς. Αυτό το παράδειγμα περιλαμβάνει τα ακόλουθα στάδια:

  1. Αποστολή αίτησης εξαγωγής.
  2. Ανίχνευση.
  3. Λήψη του αρχείου.
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;
    }
}

Ζητήματα προς εξέταση και περιορισμοί

  • Η εξαγωγή μιας σελιδοποιημένης αναφοράς που διαθέτει ένα σημασιολογικό μοντέλο Power BI ως προέλευση δεδομένων της, δεν υποστηρίζεται στις ακόλουθες περιπτώσεις:

    • Το πρόγραμμα κλήσης είναι ένα προφίλ κύριας υπηρεσίας.
    • Μία από τις προελεύσεις δεδομένων του μοντέλου σημασιολογίας έχει ρυθμιστεί με ενεργοποιημένη την καθολική σύνδεση (SSO) και παρέχεται μια αποτελεσματική ταυτότητα.
    • Το σημασιολογικό μοντέλο Power BI έχει DirectQuery για Υπηρεσίες Ανάλυσης του Azure ή άλλο σημασιολογικό μοντέλο Power BI και παρέχεται μια αποτελεσματική ταυτότητα.

  • Η εξαγωγή μιας σελιδοποιημένης αναφοράς που έχει Υπηρεσίες Ανάλυσης του Azure προέλευση δεδομένων που έχει ρυθμιστεί με ενεργοποιημένη την καθολική σύνδεση (SSO), δεν υποστηρίζεται στις ακόλουθες περιπτώσεις:

    • Το πρόγραμμα κλήσης είναι ένα προφίλ κύριας υπηρεσίας.
    • Ο καλών είναι ένας κύριος χρήστης και παρέχεται μια αποτελεσματική ταυτότητα.

  • Για να εξαγάγετε μια σελιδοποιημένη αναφορά με μια αποτελεσματική ταυτότητα, το όνομα χρήστη πρέπει να είναι ένας υπάρχων χρήστης από το αναγνωριστικό Microsoft Entra του μισθωτή σας.

  • Η εξαγωγή μιας αναφοράς περιορίζεται σε 60 λεπτά, τα οποία αντιστοιχούν στη διάρκεια ζωής του διακριτικού πρόσβασης χρήστη. Εάν λάβετε ένα σφάλμα χρονικού ορίου μετά το όριο των 60 λεπτών κατά την εξαγωγή μεγάλων ποσοτήτων δεδομένων, εξετάστε το ενδεχόμενο μείωσης της ποσότητας δεδομένων χρησιμοποιώντας κατάλληλα φίλτρα.

  • Η υπερ-σύνδεση διεύθυνσης URL κοινής χρήσης αρχείου (κοινή χρήση αρχείου /διαδρομή UNC) δεν λειτουργεί κατά την εξαγωγή μιας δημοσιευμένης σελιδοποιημένης αναφοράς στο Υπηρεσία Power BI online.

Σχετικό περιεχόμενο

Δείτε πώς μπορείτε να ενσωματώσετε περιεχόμενο για τους πελάτες και τον οργανισμό σας: