Power BI raporunu dosyaya aktarma

Makale
12/19/2023

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

.pptx (PowerPoint)
.Pdf
.png
- .png dosyasına aktardığınızda, birden çok sayfası olan bir rapor .zip dosyasına sıkıştırılır
- .zip dosyasındaki her dosya bir rapor sayfasını temsil eder
- Sayfa adları, Grup API'lerinde Sayfaları Al veya Sayfaları Al'ın dönüş değerleriyle aynıdır

Dekont

ExportToFile API'sini kullanarak bir Power BI raporunu bir dosyaya dışarı aktarmak, Kullanıcı Başına Premium (PPU) için desteklenmez.

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. Yer işaretlerini kullanarak, raporu yapılandırılmış filtreler, dilimleyiciler ve diğer ayarlar gibi 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. Daha fazla bilgi için bkz . Power Automate ile Power BI raporunu dışarı aktarma ve e-posta ile gönderme

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) için desteklenmez.

Yönetici ayarları

API'yi kullanmadan önce aşağıdaki yönetici kiracı ayarlarının etkinleştirildiğini doğrulayın:

Raporları PowerPoint sunuları veya PDF belgeleri olarak dışarı aktarma - Varsayılan olarak etkindir.
Raporları görüntü dosyası olarak dışarı aktarma - Yalnızca .png için gereklidir ve varsayılan olarak devre dışı bırakılır.

"İşleme" olayları

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.

Yoklama sırasında API, tamamlanan çalışma miktarını temsil eden bir sayı döndürür. Her dışarı aktarma işindeki çalışma, işteki dışarı aktarmaların toplamına göre hesaplanır. Dışarı aktarma işlemi, tek bir görseli veya yer işareti olan veya olmayan bir sayfayı dışarı aktarmayı içerir. Tüm dışarı aktarmalar aynı ağırlığa sahiptir. Örneğin, dışarı aktarma işiniz 10 sayfalı bir raporu dışarı aktarmayı içeriyorsa ve yoklama 70 döndürüyorsa, bu API'nin dışarı aktarma işinde 10 sayfadan yedisini işlediği anlamına gelir.

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

Bu bölümde aşağıdaki desteklenen özelliklerin nasıl kullanılacağı açıklanmaktadır:

Hangi sayfaların yazdırılacağını seçme
Sayfayı veya tek bir görseli dışarı aktarma
Bookmarks
Filtreler
Kimlik Doğrulaması
Satır Düzeyi Güvenlik (RLS)
Veri koruma
Yerelleştirme
Dinamik bağlama

Hangi sayfaların yazdırılacağını seçme

Yazdırmak istediğiniz sayfaları, Sayfaları Al veya Gruptaki Sayfaları Al dönüş değerine göre belirtin. Dışarı aktardığınız sayfaların sırasını da belirtebilirsiniz.

Sayfayı veya tek bir görseli dışarı aktarma

Dışarı aktarılacak sayfayı veya tek bir görseli belirtebilirsiniz. Sayfalar yer işaretleri ile veya yer işaretleri olmadan dışarı aktarılabilir.

Dışarı aktarma türüne bağlı olarak, ExportReportPage nesnesine farklı öznitelikler geçirmeniz gerekir. Aşağıdaki tablo, her dışarı aktarma işi için hangi özniteliklerin gerekli olduğunu belirtir.

Dekont

Tek bir görseli dışarı aktarmak, sayfayı dışarı aktarmayla aynı ağırlığa sahiptir (yer işaretleriyle veya yer işaretleri olmadan). Bu, sistem hesaplamaları açısından her iki işlemin de aynı değeri taşıdığı anlamına gelir.

Öznitelik	Sayfa	Yorumlar
`bookmark`	İsteğe bağlı	Belirli bir durumdaki bir sayfayı dışarı aktarmak için kullanın
`pageName`		GetPages REST API'sini veya istemci API'sini `getPages`kullanın.
`visualName`		Görselin adını almanın iki yolu vardır: İstemci API'sini `getVisuals`kullanın. Bir görsel seçildiğinde tetiklenen visualClicked olayını dinleyin ve günlüğe yazın. Daha fazla bilgi için bkz. Olayları işleme .

Yer işaretleri

Yer işaretleri, uygulanan filtreler ve raporun görsellerinin durumu da dahil olmak üzere belirli bir yapılandırmada rapor kaydetmek için kullanılabilir. ExportToFile API'sini kullanarak bir raporun yer işaretini program aracılığıyla iki şekilde dışarı aktarabilirsiniz:

Var olan bir yer işaretini dışarı aktarma

Mevcut bir rapor yer işaretini dışarı aktarmak için, yer işaretleri JavaScript API'sini kullanarak alabileceğiniz benzersiz (büyük/küçük harfe duyarlı) bir tanımlayıcı olan özelliğini kullanınname.
Raporun durumunu dışarı aktarma

Raporun geçerli durumunu dışarı aktarmak için özelliğini kullanın state . Örneğin, belirli bir kullanıcının raporda yaptığı değişiklikleri yakalamak ve kullanarak geçerli durumunda capturedBookmark.statedışarı aktarmak için yer işaretinin bookmarksManager.capture yöntemini kullanabilirsiniz.

Dekont

Kişisel yer işaretleri ve kalıcı filtreler desteklenmez.

Filtreler

reportLevelFilters PowerBIReportExportConfiguration'da kullanarak bir raporu filtrelenmiş bir koşulda dışarı aktarabilirsiniz.

Filtre uygulanmış bir raporu dışarı aktarmak için, filtreniz olarak kullanmak istediğiniz URL sorgu dizesi parametrelerini ExportFilter'a ekleyin. Dizeyi girdiğinizde, URL sorgu parametresinin bölümünü kaldırmanız ?filter= gerekir.

tabloda, öğesine geçirebileceğiniz ExportFilterdizelerin birkaç söz dizimi örneği yer alır.

Filtre	Sözdizimi	Örnek
Alandaki bir değer	Tablo/Alan eq 'value'	Store/Territory eq 'NC'
Bir alanda birden çok değer	Içindeki Tablo/Alan ('değer1', 'değer2')	Depolama/Bölge: ('NC', 'TN')
Bir alanda ayrı bir değer ve başka bir alanda farklı bir benzersiz değer	Table/Field1 eq 'value1' ve Table/Field2 eq 'value2'	Store/Territory eq 'NC' ve Store/Chain eq 'Fashions Direct'

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)

Satır Düzeyi Güvenlik (RLS) ile yalnızca belirli kullanıcılara görünen 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ülemesini sağlayabilirsiniz.

RLS kullanarak dışarı aktarmak için aşağıdaki izinlere sahip olmanız gerekir:

Raporun bağlı olduğu anlam modeli için yazma ve yeniden paylaşma izinleri
Raporun bulunduğu çalışma alanının çalışma alanı üyesi veya yöneticisi

Veri koruması

.pdf ve .pptx biçimleri duyarlılık etiketlerini destekler. Duyarlılık etiketine sahip bir raporu .pdf veya .pptx dosyasına dışarı aktarırsanız, dışarı aktarılan dosya raporu duyarlılık etiketiyle birlikte görüntüler.

Duyarlılık etiketine sahip bir rapor hizmet sorumlusu kullanılarak .pdf veya .pptx dosyasına aktarılamaz.

Yerelleştirme

API'yi exportToFile kullanırken istediğiniz yerel ayarı geçirebilirsiniz. Yerelleştirme ayarları, örneğin biçimlendirmeyi seçilen yerele göre değiştirerek raporun görüntülenme biçimini etkiler.

Dinamik bağlama

Raporu, varsayılan semantik modelden başka bir anlam modeline bağlıyken dışarı aktarmak için API'yi çağırırken parametresinde datasetToBind gerekli veri kümesi kimliğini belirtin. Dinamik bağlama hakkında daha fazla bilgi edinin.

Eş zamanlı istekler

API sınırlı exportToFile sayıda eşzamanlı isteği destekler. Desteklenen en fazla eşzamanlı istek sayısı kapasite başına 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. Raporun yalnızca beş sayfası aynı anda işlenir. Örneğin, 50 sayfalı bir raporu dışarı aktarıyorsanız, dışarı aktarma işi 10 sıralı aralıkta işlenir. Dışarı aktarma işinizi iyileştirirken, birkaç işi paralel olarak yürütmeyi düşünebilirsiniz.

Kod örnekleri

Dışarı aktarma işi oluşturduğunuzda izleyebileceğiniz dört adım vardır:

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

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 için dışarı aktarma isteği gönderilir.

private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId,
    FileFormat format,
    IList<string> pageNames = null, /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
    var powerBIReportExportConfiguration = new PowerBIReportExportConfiguration
    {
        Settings = new ExportReportSettings
        {
            Locale = "en-us",
        },
        // Note that page names differ from the page display names
        // To get the page names use the GetPages REST API
        Pages = pageNames?.Select(pn => new ExportReportPage(Name = pn)).ToList(),
        // ReportLevelFilters collection needs to be instantiated explicitly
        ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

    };

    var exportRequest = new ExportReportRequest
    {
        Format = format,
        PowerBIReportConfiguration = powerBIReportExportConfiguration,
    };

    // The 'Client' object is an instance of the Power BI .NET SDK
    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<HttpOperationResponse<Export>> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the PostExportRequest response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    HttpOperationResponse<Export> httpMessage = null;
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int c_secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations 
            return null;
        }

        // The 'Client' object is an instance of the Power BI .NET SDK
        httpMessage = await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
        exportStatus = httpMessage.Body;

        // You can track the export progress using the PercentComplete that's part of the response
        SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(), exportStatus.PercentComplete);
        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 not always populated
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;
            await Task.Delay(retryAfterInSec * c_secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return httpMessage;
}

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 PollExportRequest response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        // The 'Client' object is an instance of the Power BI .NET SDK
        var fileStream = await Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
        return new ExportedFile
        {
            FileStream = fileStream,
            FileSuffix = export.ResourceFileExtension,
        };
    }
    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string FileSuffix;
}

4. Adım - Dosya akışını kullanma

Dosya akışına sahip olduğunuzda, bunu gereksinimlerinize en uygun şekilde işleyebilirsiniz. Örneğin, e-postayla gönderebilirsiniz veya dışarı aktarılan raporları indirmek için kullanabilirsiniz.

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> ExportPowerBIReport(
	Guid reportId,
	Guid groupId,
	FileFormat format,
	int pollingtimeOutInMinutes,
	CancellationToken token,
	IList<string> pageNames = null,  /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
	const int c_maxNumberOfRetries = 3; /* Can be set to any desired number */
	const int c_secToMillisec = 1000;
	try
	{
		Export export = null;
		int retryAttempt = 1;
		do
		{
			var exportId = await PostExportRequest(reportId, groupId, format, pageNames, urlFilter);
			var httpMessage = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
			export = httpMessage.Body;
			if (export == null)
			{
				// Error, failure in exporting the report
				return null;
			}
			if (export.Status == ExportState.Failed)
			{
				// Some failure cases indicate that the system is currently busy. The entire export operation can be retried after a certain delay
				// In such cases the recommended waiting time before retrying the entire export operation can be found in the RetryAfter header
				var retryAfter = httpMessage.Response.Headers.RetryAfter;
				if(retryAfter == null)
				{
				    // Failed state with no RetryAfter header indicates that the export failed permanently
				    return null;
                }

                var retryAfterInSec = retryAfter.Delta.Value.Seconds;
                await Task.Delay(retryAfterInSec * c_secToMillisec);
            }
        }
        while (export.Status != ExportState.Succeeded && retryAttempt++ < c_maxNumberOfRetries);

        if (export.Status != ExportState.Succeeded)
        {
            // Error, failure in exporting the report
            return null;
        }

        var exportedFile = await GetExportedFile(reportId, groupId, export);

        // Now you have the exported file stream ready to be used according to your specific needs
        // For example, saving the file can be done as follows:
        /*
            var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;

            using (var fileStream = File.Create(pathOnDisk))
            {
                exportedFile.FileStream.CopyTo(fileStream);
            }
        */

        return exportedFile;
    }
    catch
    {
        // Error handling
        throw;
    }
}

Dikkat edilecekler ve sınırlamalar

Dışarı aktarma API'si işlem yükü, Premium kapasite yükü değerlendirmesi bölümünde açıklandığı gibi yavaş çalışan bir arka plan işlemi olarak değerlendirilir.
Dışarı aktardığınız rapordaki tüm ilgili anlam modelleri, Doğrudan Sorgu bağlantısına sahip anlam modelleri de dahil olmak üzere Premium veya Embedded kapasitede bulunmalıdır.
Dışarı aktarılan raporlar 250 MB dosya boyutunu aşamaz.
.png'ye aktarırken duyarlılık etiketleri desteklenmez.
Dışarı aktarılan tek bir rapora dahil edilebilen dışarı aktarma sayısı (tek görseller veya rapor sayfaları) 50'dir (sayfalandırılmış raporları dışarı aktarma dahil değildir). İstek daha fazla dışarı aktarma içeriyorsa, API bir hata döndürür ve dışarı aktarma işi iptal edilir.
Power BI raporunu dosyaya aktarma için kişisel yer işaretleri ve kalıcı filtreler desteklenmez.
API, exportToFile yer işaretleri veya reportLevelFilters olmadan kullanıldığında raporu varsayılan değerle dışarı aktarır.
Burada listelenen Power BI görselleri desteklenmez. Bu görselleri içeren bir raporu dışarı aktardığınızda, raporun bu görselleri içeren bölümleri işlenmez ve bir hata simgesi görüntülenir.
- Sertifikasız Power BI özel görselleri
- R görselleri
- PowerApps
- Python görselleri
- Power Automate
- Sayfalandırılmış rapor görseli
- Visio
- ArcGIS görselleri

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

Diğer Sorularınız mı var? Power BI Topluluğu deneyin

Power BI raporunu dosyaya aktarma

Kullanım örnekleri

API'yi kullanma

Lisans gereksinimleri

Yönetici ayarları

"İşleme" olayları

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

Desteklenen özellikler

Hangi sayfaların yazdırılacağını seçme

Sayfayı veya tek bir görseli dışarı aktarma

Yer işaretleri

Filtreler

Kimlik Doğrulaması

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

Veri koruması

Yerelleştirme

Dinamik bağlama

Eş zamanlı istekler

Kod örnekleri

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

2. Adım - yoklama

3. Adım - dosyayı alma

4. Adım - Dosya akışını kullanma

Uçtan uca örnek

Dikkat edilecekler ve sınırlamalar

Geri Bildirim

Geri Bildirim

Ek kaynaklar

Power BI raporunu dosyaya aktarma

Kullanım örnekleri

API'yi kullanma

Lisans gereksinimleri

Yönetici ayarları

"İşleme" olayları

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

Desteklenen özellikler

Hangi sayfaların yazdırılacağını seçme

Sayfayı veya tek bir görseli dışarı aktarma

Yer işaretleri

Filtreler

Kimlik Doğrulaması

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

Veri koruması

Yerelleştirme

Dinamik bağlama

Eş zamanlı istekler

Kod örnekleri

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

2. Adım - yoklama

3. Adım - dosyayı alma

4. Adım - Dosya akışını kullanma

Uçtan uca örnek

Dikkat edilecekler ve sınırlamalar

İlgili içerik

Geri Bildirim

Geri Bildirim

Ek kaynaklar