ส่งออกรายงาน 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 เหตุการณ์ "การแสดงผล" และเริ่มต้นการส่งออกเมื่อการแสดงผลเสร็จสิ้นเท่านั้น

การโพลล์

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

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

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

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

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

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

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

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

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

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

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

หมายเหตุ

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

แอตทริบิวต์	เพจ	วิชวลเดียว	ข้อคิดเห็น
bookmark	เลือกได้		ใช้ เพื่อส่งออกหน้าในสถานะที่ระบุ
pageName			ใช้ GetPages REST API หรือ getPages CLIENT API
visualName			มีสองวิธีในการรับชื่อของวิชวล: ใช้ 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 MB
• เมื่อส่งออกไปยัง.png จะไม่รองรับป้ายชื่อระดับความลับ
• จํานวนการส่งออก (วิชวลเดียวหรือหน้ารายงาน) ที่สามารถรวมอยู่ในรายงานที่ส่งออกรายงานเดียวคือ 50 (ไม่รวมการส่งออกรายงานที่มีการแบ่งหน้า) หากคําขอมีการส่งออกเพิ่มเติม API จะส่งกลับข้อผิดพลาดและงานส่งออกจะถูกยกเลิก
• ไม่รองรับบุ๊กมาร์ก ส่วนบุคคลและ ตัวกรอง แบบถาวรสําหรับการส่งออกรายงาน Power BI ไปยังไฟล์
• exportToFile API ส่งออกรายงานที่มีค่าเริ่มต้นถ้าใช้โดยไม่มีบุ๊กมาร์กหรือ reportLevelFilters
• ไม่รองรับการส่งออกรายงาน Power BI ที่เชื่อมต่อกับแบบจําลองความหมายแบบรวมอย่างน้อยหนึ่งรายการ ซึ่งมีแหล่งข้อมูลภายนอกอย่างน้อยหนึ่งรายการที่มีการเปิดใช้งานการลงชื่อเข้าระบบครั้งเดียว (SSO) เมื่อส่งออก วิชวลอาจแสดงผลไม่ถูกต้อง
• เมื่อส่งออกรายงานที่มีการผูกแบบไดนามิกโดยใช้ exportToFile REST API แบบจําลองความหมายที่ผูกไว้แบบไดนามิกไม่สามารถเป็นแบบจําลองแบบรวมที่มีคิวรีโดยตรงไปยัง SQL Server Analysis Services (SSAS)
• ไม่รองรับวิชวล Power BI ที่แสดงในที่นี้ เมื่อคุณส่งออกรายงานที่มีวิชวลเหล่านี้ ส่วนของรายงานที่ประกอบด้วยวิชวลเหล่านี้จะไม่แสดง และแสดงสัญลักษณ์ข้อผิดพลาด
  • วิชวลแบบกําหนดเองของ Power BI ที่ไม่ผ่านการรับรอง
  • วิชวล R
  • PowerApps
  • วิชวล Python
  • Power Automate
  • วิชวลรายงานที่มีการแบ่งหน้า
  • Visio
  • วิชวล ArcGIS

เนื้อหาที่เกี่ยวข้อง

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

• ส่งออกรายงานที่มีการแบ่งหน้าไปยังไฟล์
• การฝังตัวสําหรับลูกค้าของคุณ
• การฝังตัวสําหรับองค์กรของคุณ
• ส่งออกและส่งอีเมลรายงาน Power BI ด้วย Power Automate

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