Sayfalandırılmış raporu dosyaya aktarma

exportToFile API'si, 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
Resim
Görüntüye aktarırken, OutputFormat biçimi ayarı aracılığıyla görüntü biçimini ayarlayın. Desteklenen OutputFormat değerleri ş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 .pptxolarak 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, Kullanıcı Başına Premium (PPU)'daki sınırlı desteğe sahiptir.

Olayları işleme

Dışarı aktarma işleminin görsel işleme tamamlanmadan 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.

Yoklama

API zaman uyumsuzdur. exportToFile API'si çağrıldığında bir dışarı aktarma işi tetikler. Dışa aktarma işini başlattıktan sonra, işi tamamlanana kadar 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 Bilgisi parametrelerine eşdeğerdir.

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

İlk dört sayfayı .pptx olarak dışa aktarma

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

Üçüncü sayfayı .jpeg olarak dışa aktarma

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

Rapor parametreleri

exportToFile API'sini kullanarak bir rapor parametresi kümesi içeren bir raporu program aracılığıyla dışarı aktarabilirsiniz. Bu, 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ğrulama

bir kullanıcı (veya ana kullanıcı) ya dahizmet 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"}
            ]
      }
}

Tek 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 https://database.windows.net.
Dataverse için kaynak, ortamınızın https:// adresidir. Ö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

exportToFile sınırlı sayıda eşzamanlı isteği destekler. eşzamanlı sayfalandırılmış rapor işleme isteği sayısının ü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ğine 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ı buradanindirilebilir.

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

İhracat 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ışa aktarma isteğini gönderme.
Yoklama.
Dosyasınıalma.

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 edilmesi gerekenler ve sınırlamalar

Uyarı

Sayfalandırılmış raporu hizmet sorumlusu profil çağıranı ile dışarı aktarmak artık veri kaynağı anlamsal bir model olduğunda destekleniyor.

Veri kaynağı olarak Power BI anlam modeline sahip bir sayfalandırılmış raporu dışarı aktarmak aşağıdaki durumlarda desteklenmez:
- Anlamsal modelin veri kaynaklarından biri, tek oturum açma (SSO) etkin olarak yapılandırılmıştır ve etkili bir kimlik sağlanmıştır.
- Power BI anlam modeli, Azure Analysis Services'e veya başka bir Power BI anlam modeline DirectQuery özelliğine 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, hizmet sorumlusu profili'dir.
- Arayan, ana kullanıcıdır ve geçerli 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.
Dosya paylaşımı URL'si köprüsü (dosya paylaşımı /UNC yolu), Power BI hizmetinde yayımlanan sayfalandırılmış raporu çevrimiçi dışarı aktarırken çalışmaz.

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

Raporu dosyaya aktar
müşterileriniz için Ekleme
Kuruluşunuz için Ekleme

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-12-15