ส่งออกรายงาน Power BI ไปยังไฟล์

exportToFile API เปิดใช้งานการส่งออกรายงาน Power BI โดยใช้การเรียกใช้ REST รูปแบบไฟล์ต่อไปนี้ได้รับการรองรับ:

  • .pptx (PowerPoint)
  • Pdf
  • .png
    • เมื่อคุณส่งออกเป็น .png รายงานที่มีหลายหน้าจะถูกบีบอัดเป็นไฟล์ .zip
    • แต่ละไฟล์ใน .zip แสดงหน้ารายงาน
    • ชื่อหน้าจะเหมือนกับค่าที่ส่งกลับของ API รับหน้าหรือรับหน้าในกลุ่ม

หมายเหตุ

การส่งออกรายงาน Power BI ไปยังไฟล์โดยใช้ exportToFile API ไม่ได้รับการรองรับสําหรับ Premium Per User (PPU)

ตัวอย่างการใช้

คุณสามารถใช้คุณลักษณะการส่งออกได้หลายวิธี ต่อไปนี้คือตัวอย่างสองตัวอย่าง:

  • ส่งไปยังปุ่ม พิมพ์ - ในแอปพลิเคชันของคุณ ให้สร้างปุ่มที่เมื่อคลิกที่จะทริกเกอร์งานการส่งออก งานสามารถส่งออกรายงานที่ดูเป็น .pdf หรือ .pptx เมื่อเสร็จสมบูรณ์ ผู้ใช้สามารถรับไฟล์เป็นการดาวน์โหลดได้ ด้วยการใช้บุ๊กมาร์ก คุณสามารถส่งออกรายงานในสถานะที่ระบุ รวมถึงตัวกรองที่กําหนดค่า ตัวแบ่งส่วนข้อมูล และการตั้งค่าอื่น ๆ ในฐานะที่เป็น API แบบอะซิงโครนัส อาจใช้เวลาสักครู่เพื่อให้ไฟล์พร้อมใช้งาน

  • ไฟล์แนบ อีเมล - ส่งอีเมลอัตโนมัติในช่วงเวลาที่ตั้งค่า ด้วยรายงาน .pdf ที่แนบมา สถานการณ์นี้อาจเป็นประโยชน์ถ้าคุณต้องการส่งรายงานรายสัปดาห์ไปยังผู้บริหารโดยอัตโนมัติ สําหรับข้อมูลเพิ่มเติม ดู การส่งออกและส่งอีเมลรายงาน Power BI ด้วย Power Automate

การใช้ API

ข้อกำหนดสิทธิการใช้งาน

  • รายงานที่คุณกําลังส่งออกต้องอยู่ในพื้นที่ทํางานที่ได้รับการสนับสนุนโดยความจุ Premium, Embedded หรือ Fabric
  • exportToFile API ไม่ได้รับการสนับสนุนสําหรับ Premium Per User (PPU)

การตั้งค่าของผู้ดูแลระบบ

ก่อนที่จะใช้ API ให้ตรวจสอบว่ามีการเปิดใช้งานการตั้งค่าผู้เช่าของผู้ดูแลระบบต่อไปนี้:

  • ส่งออกรายงานในรูปแบบงานนําเสนอ PowerPoint หรือเอกสาร PDF - เปิดใช้งานตามค่าเริ่มต้น
  • ส่งออกรายงานเป็นไฟล์ รูปภาพ - จําเป็นสําหรับ .png เท่านั้นและปิดใช้งานตามค่าเริ่มต้น

เหตุการณ์ "การแสดงผล"

เมื่อต้องการตรวจสอบให้แน่ใจว่าการส่งออกไม่ได้เริ่มต้นขึ้นก่อนการแสดงผลด้วยภาพเสร็จสิ้น ให้ใช้ API เหตุการณ์ "การแสดงผล" และเริ่มต้นการส่งออกเมื่อการแสดงผลเสร็จสิ้นเท่านั้น

Polling

API เป็นแบบอะซิงโครนัส เมื่อมีการ เรียกใช้ API exportToFile จะทริกเกอร์งานการส่งออก หลังจากทริกเกอร์งานส่งออก ให้ใช้ การ โพลล์เพื่อติดตามงานจนกว่าจะเสร็จสมบูรณ์

ในระหว่างการโพลล์ API จะส่งกลับตัวเลขที่แสดงถึงจํานวนการทํางานที่เสร็จสมบูรณ์ งานในแต่ละงานส่งออกจะถูกคํานวณจากผลรวมของการส่งออกในงาน การส่งออกรวมถึงการส่งออกวิชวลเดียวหรือหน้าที่มีหรือไม่มีบุ๊กมาร์ก การส่งออกทั้งหมดมีน้ําหนักเท่ากัน ตัวอย่างเช่น หากงานส่งออกของคุณมีการส่งออกรายงานที่มี 10 หน้าและการโพลล์ส่งกลับ 70 หน้า นั่นหมายความว่า API ได้รับการประมวลผล 7 จาก 10 หน้าในงานส่งออก

เมื่อการส่งออกเสร็จสมบูรณ์ การเรียกใช้ API การโพลล์จะส่งกลับ URL ของ Power BI สําหรับการรับไฟล์ URL พร้อมใช้งานเป็นเวลา 24 ชั่วโมง

คุณลักษณะที่รองรับ

ในส่วนนี้จะอธิบายวิธีการใช้คุณลักษณะที่ได้รับการสนับสนุนต่อไปนี้:

การเลือกหน้าที่จะพิมพ์

ระบุหน้าที่คุณต้องการพิมพ์ตามค่าส่งคืนการรับหน้าหรือรับหน้าในกลุ่ม คุณยังสามารถระบุลําดับของหน้าที่คุณกําลังส่งออกได้

การส่งออกหน้าหรือวิชวลเดียว

คุณสามารถระบุหน้าหรือวิชวลเดียวเพื่อส่งออกได้ สามารถส่งออกหน้าที่มีหรือไม่มีบุ๊กมาร์กได้

ขึ้นอยู่กับชนิดของการส่งออก คุณจําเป็นต้องส่งผ่านแอตทริบิวต์ที่แตกต่างกันไปยังวัตถุ ExportReportPage ตารางต่อไปนี้ระบุแอตทริบิวต์ที่จําเป็นสําหรับงานส่งออกแต่ละงาน

หมายเหตุ

การส่งออกวิชวลเดียวจะมีน้ําหนักเหมือนกับการส่งออกหน้า (มีหรือไม่มีบุ๊กมาร์ก) การดําเนินการทั้งสองอย่างจะมีค่าเดียวกัน

แอตทริบิวต์ เพจ วิชวลเดียว ความคิดเห็น
bookmark เลือกได้ Does not apply to. ใช้ เพื่อส่งออกหน้าในสถานะที่ระบุ
pageName Applies to. Applies to. ใช้ GetPages REST API หรือ getPages CLIENT API
visualName Does not apply to. Applies to. มีสองวิธีในการรับชื่อของวิชวล:
  • ใช้ API ไคลเอ็นต์getVisuals
  • ฟังและบันทึก เหตุการณ์ visualClicked ซึ่งจะถูกทริกเกอร์เมื่อเลือกวิชวล สําหรับข้อมูลเพิ่มเติม ดู วิธีการจัดการเหตุการณ์
  • .

    บุ๊กมาร์ก

    บุ๊กมาร์ก สามารถใช้ในการบันทึกรายงานในการกําหนดค่าเฉพาะรวมถึงตัวกรองที่ใช้และสถานะของวิชวลของรายงาน คุณสามารถใช้ API exportToFile เพื่อส่งออกบุ๊กมาร์กของรายงานโดยทางโปรแกรมได้สองวิธี:

    • ส่งออกบุ๊กมาร์กที่มีอยู่

      หากต้องการส่งออกบุ๊กมาร์กรายงานที่มีอยู่ ให้ใช้nameคุณสมบัติ ซึ่งเป็นตัวระบุที่ไม่ซ้ํากัน (ตรงตามตัวพิมพ์ใหญ่-เล็ก) ซึ่งคุณสามารถรับได้โดยใช้ที่คั่นหน้า JavaScript API

    • ส่งออกสถานะของรายงาน

      เมื่อต้องการส่งออกสถานะปัจจุบันของรายงาน ให้ใช้ state คุณสมบัติ ตัวอย่างเช่น คุณสามารถใช้วิธีการของbookmarksManager.captureบุ๊กมาร์กเพื่อจับภาพการเปลี่ยนแปลงผู้ใช้ที่ระบุที่ทํากับรายงาน จากนั้นส่งออกในสถานะปัจจุบันโดยใช้capturedBookmark.state

    หมายเหตุ

    ไม่รองรับบุ๊กมาร์ก ส่วนบุคคลและ ตัวกรอง แบบถาวร

    ตัวกรอง

    การใช้ reportLevelFilters ใน PowerBIReportExportConfiguration คุณสามารถส่งออกรายงานในเงื่อนไขที่ถูกกรองได้

    เมื่อต้องการส่งออกรายงานที่ถูกกรอง ให้แทรกพารามิเตอร์สตริงแบบสอบถาม URL ที่คุณต้องการใช้เป็นตัวกรองของคุณ เพื่อ ExportFilter เมื่อคุณใส่สตริงที่ คุณต้องเอาส่วนของ ?filter= พารามิเตอร์แบบสอบถาม URL ออก

    ตารางนี้ประกอบด้วยตัวอย่างของสตริงที่คุณสามารถส่งผ่านไปยัง ExportFilterได้

    ตัวกรอง ไวยากรณ์ ตัวอย่าง
    ค่าในเขตข้อมูล ตาราง/ฟิลด์ eq 'ค่า' ร้านค้า/อาณาเขต eq 'NC'
    หลายค่าในเขตข้อมูล ตาราง/เขตข้อมูลใน ('value1', 'value2') ร้านค้า/อาณาเขตใน ('NC', 'TN')
    ค่าที่แตกต่างกันในเขตข้อมูลหนึ่งและค่าที่แตกต่างกันในเขตข้อมูลอื่น ตาราง/Field1 eq 'value1' และตาราง/Field2 eq 'value2' ร้านค้า/อาณาเขต eq 'NC' และร้านค้า/เครือข่าย eq 'Fashions Direct'

    การรับรองความถูกต้อง

    คุณสามารถรับรองความถูกต้องได้โดยใช้ผู้ใช้ (หรือผู้ใช้หลัก) หรือหลักบริการ

    การรักษาความปลอดภัยระดับแถว (RLS)

    ด้วยการ รักษาความปลอดภัยระดับแถว (RLS) คุณสามารถส่งออกรายงานที่แสดงข้อมูลที่สามารถมองเห็นได้เฉพาะผู้ใช้บางรายเท่านั้น ตัวอย่างเช่น ถ้าคุณกําลังส่งออกรายงานยอดขายที่กําหนดไว้ด้วยบทบาทภูมิภาค คุณสามารถกรองรายงานเพื่อให้แสดงเฉพาะภูมิภาคบางภูมิภาคเท่านั้นได้

    เมื่อต้องการส่งออกโดยใช้ RLS คุณต้องมีสิทธิ์ต่อไปนี้:

    • สิทธิ์การเขียนและแชร์ต่อสําหรับแบบจําลองความหมายที่รายงานเชื่อมต่ออยู่
    • สมาชิกพื้นที่ทํางานหรือผู้ดูแลระบบของพื้นที่ทํางานที่มีรายงานอยู่

    การปกป้องข้อมูล

    รูปแบบ .pdf และ .pptx สนับสนุน ป้ายชื่อระดับความลับ หากคุณส่งออกรายงานที่มีป้ายชื่อระดับความลับเป็น .pdf หรือ .pptx ไฟล์ที่ส่งออกจะแสดงรายงานที่มีป้ายชื่อระดับความลับ

    รายงานที่มีป้ายชื่อระดับความลับไม่สามารถส่งออกเป็น .pdf หรือ .pptx โดยใช้ บริการหลักได้

    การแปลเป็นภาษาท้องถิ่น

    เมื่อใช้ exportToFile API คุณสามารถผ่านตําแหน่งที่ตั้งที่คุณต้องการได้ การตั้งค่าการแปลเป็นภาษาท้องถิ่นมีผลต่อวิธีแสดงรายงาน ตัวอย่างเช่น โดยการเปลี่ยนการจัดรูปแบบตามท้องถิ่นที่เลือก

    การผูกแบบไดนามิก

    หากต้องการส่งออกรายงานในขณะที่เชื่อมต่อกับแบบจําลองความหมายอื่นจากนั้นระบุรหัสชุดข้อมูลที่จําเป็นใน datasetToBind พารามิเตอร์เมื่อเรียกใช้ API อ่านเพิ่มเติมเกี่ยวกับ การผูกแบบไดนามิก

    คําขอที่เกิดขึ้นพร้อมกัน

    exportToFile API สนับสนุนจํานวนคําขอที่เกิดขึ้นพร้อมกันจํานวนจํากัด จํานวนสูงสุดของคําขอที่เกิดขึ้นพร้อมกันที่สนับสนุนคือ 500 ต่อความจุ เพื่อหลีกเลี่ยงไม่ให้เกินขีดจํากัดและได้รับข้อผิดพลาด คําขอมากเกินไป (429) ให้กระจายโหลดเมื่อเวลาผ่านไปหรือผ่านความจุ มีการประมวลผลรายงานเพียงห้าหน้าเท่านั้นพร้อมๆ กัน ตัวอย่างเช่น ถ้าคุณกําลังส่งออกรายงานที่มี 50 หน้า งานส่งออกจะได้รับการประมวลผลในช่วงเวลา 10 ลําดับ เมื่อปรับงานส่งออกของคุณให้เหมาะสม คุณอาจต้องการพิจารณาการดําเนินงานบางอย่างแบบขนาน

    ตัวอย่างรหัส

    เมื่อคุณสร้างงานส่งออก มีสี่ขั้นตอนในการปฏิบัติตามต่อไปนี้:

    1. ส่งคําขอการส่งออก
    2. การโพลล์
    3. การรับไฟล์
    4. การใช้สตรีมไฟล์

    ส่วนนี้มีตัวอย่างสําหรับแต่ละขั้นตอน

    ขั้นตอนที่ 1 - ส่งคําขอส่งออก

    ขั้นตอนแรกคือการส่งคําขอส่งออก ในตัวอย่างนี้ คําขอส่งออกจะถูกส่งสําหรับหน้าที่ระบุ

    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 - การโพลล์

    หลังจากที่คุณส่งคําขอส่งออก ให้ใช้การโพลล์เพื่อระบุว่าไฟล์ส่งออกที่คุณกําลังรออยู่พร้อมหรือไม่

    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 - การรับไฟล์

    เมื่อการโพลล์ส่งกลับ URL ให้ใช้ตัวอย่างนี้เพื่อรับไฟล์ที่ได้รับ

    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 - การใช้สตรีมไฟล์

    เมื่อคุณมีสตรีมไฟล์ คุณสามารถจัดการได้ในแบบที่เหมาะกับความต้องการของคุณที่สุด ตัวอย่างเช่น คุณสามารถส่งอีเมลหรือใช้เพื่อดาวน์โหลดรายงานที่ส่งออกได้

    ตัวอย่างแบบครบวงจร

    นี่คือตัวอย่างแบบ end-to-end สําหรับการส่งออกรายงาน ตัวอย่างนี้ประกอบด้วยขั้นตอนต่อไปนี้:

    1. ส่งคําขอการส่งออก
    2. การโพลล์
    3. การรับไฟล์
    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;
        }
    }
    

    ข้อควรพิจารณาและข้อจำกัด

    • การโหลดการดําเนินการส่งออก API จะถูกประเมินเป็นการทํางานแบบเบื้องหลังที่ทํางานช้า ตามที่อธิบายไว้ใน การประเมินการโหลดความจุแบบพรีเมียม
    • แบบจําลองความหมายที่เกี่ยวข้องทั้งหมดในรายงานที่คุณกําลังส่งออกต้องอยู่ในความจุแบบพรีเมียมหรือแบบฝังตัว รวมถึงแบบจําลองความหมายด้วยการเชื่อมต่อ Direct Query
    • รายงานที่ส่งออกต้องไม่เกิน 250 เมกะไบต์ไฟล์
    • เมื่อส่งออกเป็น .png จะไม่รองรับป้ายชื่อระดับความลับ
    • จํานวนการส่งออก (วิชวลเดียวหรือหน้ารายงาน) ที่สามารถรวมอยู่ในรายงานที่ส่งออกรายงานเดียวคือ 50 (ไม่รวมการส่งออกรายงานที่มีการแบ่งหน้า) หากคําขอมีการส่งออกเพิ่มเติม API จะส่งกลับข้อผิดพลาดและงานส่งออกจะถูกยกเลิก
    • ไม่รองรับบุ๊กมาร์ก ส่วนบุคคลและ ตัวกรอง แบบถาวรสําหรับการส่งออกรายงาน Power BI ไปยังไฟล์
    • exportToFile API ส่งออกรายงานที่มีค่าเริ่มต้นถ้าใช้โดยไม่มีบุ๊กมาร์กหรือ reportLevelFilters
    • ไม่รองรับวิชวล Power BI ที่แสดงในที่นี้ เมื่อคุณส่งออกรายงานที่มีวิชวลเหล่านี้ ส่วนของรายงานที่ประกอบด้วยวิชวลเหล่านี้จะไม่แสดง และแสดงสัญลักษณ์ข้อผิดพลาด
      • วิชวลแบบกําหนดเองของ Power BI ที่ไม่ผ่านการรับรอง
      • วิชวล R
      • PowerApps
      • วิชวล Python
      • Power Automate
      • วิชวลรายงานที่มีการแบ่งหน้า
      • Visio
      • วิชวล ArcGIS

    ตรวจสอบวิธีการฝังเนื้อหาสําหรับลูกค้าและองค์กรของคุณ:

    มีคําถามเพิ่มเติมหรือไม่ ลองใช้ชุมชน Power BI