Sayfalandırılmış raporu dosyaya aktarma

Makale
09/08/2023

API, exportToFile REST çağrısı kullanarak Power BI sayfalandırılmış raporunu dışarı aktarmaya olanak tanır. Aşağıdaki dosya biçimleri desteklenir:

.pptx (PowerPoint)
.pdf (ve Erişilebilir PDF veya PDF/UA)
.xlsx (Excel)
.docx (Word)
.Csv
.Xml
.Mhtml
Görsel
Bir görüntüye dışarı aktarırken, biçim ayarı aracılığıyla OutputFormat görüntü biçimini ayarlayın. Desteklenen OutputFormat değerler şunlardır:
- .tiff (varsayılan)
- .Bmp
- .Emf
- .gif
- .jpeg
- .png

Kullanım örnekleri

Dışarı aktarma özelliğini çeşitli yollarla kullanabilirsiniz. Aşağıda birkaç örnek verilmiştir:

Yazdırmaya gönder düğmesi - Uygulamanızda, tıklandığında dışarı aktarma işini tetikleyen bir düğme oluşturun. İş, görüntülenen raporu .pdf veya .pptx olarak dışarı aktarabilir. Tamamlandığında, kullanıcı dosyayı indirme olarak alabilir. Rapor parametrelerini ve biçim ayarlarını kullanarak, filtrelenmiş veriler, özel sayfa boyutları ve biçime özgü diğer ayarlar dahil olmak üzere raporu belirli bir durumda dışarı aktarabilirsiniz. API zaman uyumsuz olduğundan dosyanın kullanılabilir olması biraz zaman alabilir.
E-posta eki - Ekli bir .pdf raporuyla belirli aralıklarla otomatik bir e-posta gönderin. Yöneticilere haftalık rapor göndermeyi otomatikleştirmek istiyorsanız bu senaryo yararlı olabilir.

API'yi kullanma

Lisans gereksinimleri

Dışarı aktardığınız raporun Premium, Embedded veya Fabric kapasitesiyle desteklenen bir çalışma alanında bulunması gerekir.
exportToFile API' nin Kullanıcı Başına Premium (PPU) desteğisınırlıdır.

Olayları işleme

Görsel işleme tamamlanmadan dışarı aktarma işleminin başlamadığından emin olmak için "İşleme" olayları API'sini kullanın ve yalnızca işleme tamamlandığında dışarı aktarmayı başlatın.

Yoklamanın Karşılaştırması

API zaman uyumsuzdur. exportToFile API'si çağrıldığında bir dışarı aktarma işi tetikler. Dışarı aktarma işini tetikledikten sonra, tamamlanana kadar işi izlemek için yoklamayı kullanın.

Dışarı aktarma işlemi tamamlandığında yoklama API'si çağrısı dosyayı almak için bir Power BI URL'si döndürür. URL 24 saat boyunca kullanılabilir.

Desteklenen özellikler

Biçim ayarları

Her dosya biçimi için çeşitli biçim ayarları belirtin. Desteklenen özellikler ve değerler, sayfalandırılmış rapor URL'si parametreleri için Cihaz Bilgileri parametrelerine eşdeğerdir.

Aşağıda iki örnek verilmiştir. Birincisi, rapor sayfası boyutunu kullanarak raporun ilk dört sayfasını bir .pptx dosyasına dışarı aktarmaktır. İkinci örnek, raporun üçüncü sayfasını bir .jpeg dosyasına dışarı aktarmaya yöneliktir.

İlk dört sayfayı .pptx'e aktarma

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

Üçüncü sayfayı .jpeg'e aktarma

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

Rapor parametreleri

API'yi exportToFile kullanarak bir rapor parametresi kümesi içeren bir raporu program aracılığıyla dışarı aktarabilirsiniz. Bu işlem rapor parametresi özellikleri kullanılarak yapılır.

Rapor parametresi değerlerini ayarlamaya yönelik bir örnek aşağıda verilmiştir.

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

Kimlik Doğrulaması

Bir kullanıcı (veya ana kullanıcı) veya hizmet sorumlusu kullanarak kimlik doğrulaması yapabilirsiniz.

Satır Düzeyi Güvenlik (RLS)

Veri kaynağı olarak tanımlanan Satır Düzeyi Güvenlik (RLS) içeren bir Power BI anlam modeli kullanırken, yalnızca belirli kullanıcılar tarafından görülebilen verileri gösteren bir raporu dışarı aktarabilirsiniz. Örneğin, bölgesel rollerle tanımlanan bir satış raporunu dışarı aktarıyorsanız, raporu program aracılığıyla filtreleyerek yalnızca belirli bir bölgenin görüntülenmesini sağlayabilirsiniz.

RLS kullanarak dışarı aktarmak için raporun veri kaynağı olarak kullandığı Power BI anlam modeli için okuma izniniz olmalıdır.

Aşağıda RLS için etkili bir kullanıcı adı sağlama örneği verilmiştir.

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

Çoklu Oturum Açma SQL ve Dataverse (SSO)

Power BI'da SSO ile OAuth'u ayarlama seçeneğiniz vardır. Bunu yaptığınızda, verileri almak için raporu görüntüleyen kullanıcının kimlik bilgileri kullanılır. İstek üst bilgisindeki erişim belirteci verilere erişmek için kullanılmaz. Belirteç, post gövdesindeki etkin kimlikle geçirilmelidir.

Erişmek istediğiniz kaynak için doğru erişim belirtecini almak bazen karmaşık olabilir.

Azure SQL için kaynak şeklindedir https://database.windows.net.
Dataverse için kaynak, ortamınızın adresidir https:// . Örneğin, https://contoso.crm.dynamics.com.

AuthenticationContext.AcquireTokenAsync yöntemini kullanarak belirteç API'sine erişin.

Aşağıda erişim belirteciyle etkili bir kimlik (kullanıcı adı) sağlama örneği verilmiştir.

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

Eş zamanlı istekler

sınırlı exportToFile sayıda eşzamanlı isteği destekler. Eşzamanlı sayfalandırılmış rapor işleme isteği sayısı üst sınırı 500'dür. Sınırı aşmamak ve Çok Fazla İstek (429) hatası almak için yükü zaman içinde veya kapasiteler arasında dağıtın.

Kullanıcı Başına Premium (PPU) ile exportToFile API, beş dakikalık bir pencerede yalnızca bir isteğe izin verir. Beş dakikalık pencere içindeki birden çok istek Çok Fazla İstek (429) hatasına neden olur.

Kod örnekleri

Kod örneklerinde kullanılan Power BI API SDK'sı buradan indirilebilir.

Dışarı aktarma işi oluşturduğunuzda izleyebileceğiniz üç adım vardır:

Dışarı aktarma isteği gönderiliyor.
Yoklama.
Dosya alınıyor.

Bu bölümde her adım için örnekler sağlanır.

1. Adım : Dışarı aktarma isteği gönderme

İlk adım bir dışarı aktarma isteği göndermektir. Bu örnekte, belirli bir sayfa aralığı, boyutu ve rapor parametresi değerleri için dışarı aktarma isteği gönderilir.

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. Adım - yoklama

Dışarı aktarma isteği gönderdikten sonra, beklediğiniz dışarı aktarma dosyasının ne zaman hazır olduğunu belirlemek için yoklamayı kullanın.

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. Adım - dosyayı alma

Yoklama bir URL döndürdüğünde, alınan dosyayı almak için bu örneği kullanın.

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

Uçtan uca örnek

Bu, raporu dışarı aktarmaya yönelik uçtan uca bir örnektir. Bu örnek aşağıdaki aşamaları içerir:

Dışarı aktarma isteği gönderiliyor.
Yoklama.
Dosya alınıyor.

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

Dikkat edilecekler ve sınırlamalar

Veri kaynağı olarak Power BI anlam modeline sahip bir sayfalandırılmış raporu dışarı aktarmak aşağıdaki durumlarda desteklenmez:
- Çağıran bir hizmet sorumlusu profilidir.
- Anlamsal modelin veri kaynaklarından biri çoklu oturum açma (SSO) etkin olarak yapılandırılır ve etkili bir kimlik sağlanır.
- Power BI anlam modeli, DirectQuery'yi Azure Analysis Services'e veya başka bir Power BI anlam modeline sahiptir ve etkili bir kimlik sağlanmıştır.
Azure Analysis Services veri kaynağının çoklu oturum açma (SSO) etkinleştirilmiş olarak yapılandırılmış olduğu sayfalandırılmış raporu dışarı aktarmak aşağıdaki durumlarda desteklenmez:
- Çağıran bir hizmet sorumlusu profilidir.
- Arayan bir ana kullanıcıdır ve etkili bir kimlik sağlanmıştır.
Etkin bir kimliğe sahip sayfalandırılmış raporu dışarı aktarmak için kullanıcı adının kiracınızın Microsoft Entra Kimliği'nden mevcut bir kullanıcı olması gerekir.
Bir raporu dışarı aktarma işlemi, kullanıcı erişim belirtecinin ömrüyle eşleşen 60 dakika ile sınırlıdır. Büyük miktarda veriyi dışarı aktarırken 60 dakikalık işareti aşan bir zaman aşımı hatası alırsanız uygun filtreleri kullanarak veri miktarını azaltmayı göz önünde bulundurun.
Çevrimiçi Power BI hizmeti yayımlanan sayfalandırılmış rapor dışarı aktarılırken dosya paylaşımı URL köprüsü (dosya paylaşımı /UNC yolu) çalışmıyor.

Müşterileriniz ve kuruluşunuz için içerik eklemeyi gözden geçirin:

Sayfalandırılmış raporu dosyaya aktarma

Kullanım örnekleri

API'yi kullanma

Lisans gereksinimleri

Olayları işleme

Yoklamanın Karşılaştırması

Desteklenen özellikler

Biçim ayarları

İlk dört sayfayı .pptx'e aktarma

Üçüncü sayfayı .jpeg'e aktarma

Rapor parametreleri

Kimlik Doğrulaması

Satır Düzeyi Güvenlik (RLS)

Çoklu Oturum Açma SQL ve Dataverse (SSO)

Eş zamanlı istekler

Kod örnekleri

1. Adım : Dışarı aktarma isteği gönderme

2. Adım - yoklama

3. Adım - dosyayı alma

Uçtan uca örnek

Dikkat edilecekler ve sınırlamalar

Geri Bildirim

Geri Bildirim

Ek kaynaklar

Sayfalandırılmış raporu dosyaya aktarma

Kullanım örnekleri

API'yi kullanma

Lisans gereksinimleri

Olayları işleme

Yoklamanın Karşılaştırması

Desteklenen özellikler

Biçim ayarları

İlk dört sayfayı .pptx'e aktarma

Üçüncü sayfayı .jpeg'e aktarma

Rapor parametreleri

Kimlik Doğrulaması

Satır Düzeyi Güvenlik (RLS)

Çoklu Oturum Açma SQL ve Dataverse (SSO)

Eş zamanlı istekler

Kod örnekleri

1. Adım : Dışarı aktarma isteği gönderme

2. Adım - yoklama

3. Adım - dosyayı alma

Uçtan uca örnek

Dikkat edilecekler ve sınırlamalar

İlgili içerik

Geri Bildirim

Geri Bildirim

Ek kaynaklar