ส่งออกรายงานที่มีการแบ่งหน้าไปยังไฟล์

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

• .pptx (PowerPoint)

• .pdf (และ PDF ที่สามารถเข้าถึงได้ หรือ PDF/UA)

• .xlsx (Excel)

• .docx (Word)

• Csv

• Xml

• .mhtml

• รูปภาพ
  เมื่อส่งออกไปยังรูปภาพ ให้ตั้งค่ารูปแบบรูปภาพผ่าน OutputFormat การตั้งค่ารูปแบบ ค่าที่ได้รับ OutputFormat การสนับสนุนคือ:

  • .tiff (ค่าเริ่มต้น)
  • Bmp
  • Emf
  • .gif
  • .jpeg
  • .png

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

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

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

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

การใช้ API

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

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

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

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

Polling

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

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

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

การตั้งค่ารูปแบบ

ระบุการตั้งค่ารูปแบบต่าง ๆ สําหรับแต่ละรูปแบบไฟล์ คุณสมบัติและค่าที่ได้รับการสนับสนุนจะเทียบเท่ากับ พารามิเตอร์ ข้อมูลอุปกรณ์สําหรับพารามิเตอร์ URL ของรายงานที่มีการแบ่งหน้า

นี่คือสองตัวอย่าง วิธีแรกคือการส่งออกสี่หน้าแรกของรายงานโดยใช้ขนาดหน้ารายงานไปยังไฟล์ .pptx ตัวอย่างที่สองใช้สําหรับการส่งออกหน้าที่สามของรายงานไปยังไฟล์ .jpeg

การส่งออกสี่หน้าแรกไปยัง .pptx

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

การส่งออกหน้าที่สามในรูปแบบ .jpeg

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

พารามิเตอร์รายงาน

คุณสามารถใช้ exportToFile API เพื่อส่งออกรายงานด้วยชุดพารามิเตอร์ของรายงานโดยทางโปรแกรม การดําเนินการนี้ทําได้โดยใช้ ความสามารถของพารามิเตอร์ รายงาน

ต่อไปนี้คือตัวอย่างสําหรับการตั้งค่าพารามิเตอร์รายงาน

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

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

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

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

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

หากต้องการส่งออกโดยใช้ RLS คุณต้องมีสิทธิ์ในการอ่านสําหรับแบบจําลองความหมายของ Power BI ที่รายงานกําลังใช้เป็นแหล่งข้อมูล

นี่คือตัวอย่างของการใส่ชื่อผู้ใช้ที่มีประสิทธิภาพสําหรับ RLS

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

SQL การลงชื่อเข้าระบบครั้งเดียวและ Dataverse (SSO)

ใน Power BI คุณมีตัวเลือกในการตั้งค่า OAuth ด้วย SSO เมื่อคุณทําเช่นนั้น ข้อมูลประจําตัวสําหรับผู้ใช้ที่ดูรายงานจะถูกใช้เพื่อดึงข้อมูล โทเค็นการเข้าถึงในส่วนหัวของคําขอไม่ได้ใช้เพื่อเข้าถึงข้อมูล โทเค็นต้องถูกส่งผ่านด้วยข้อมูลประจําตัวที่มีผลบังคับใช้ในเนื้อความโพสต์

การรับโทเค็นการเข้าถึงที่ถูกต้องสําหรับทรัพยากรที่คุณต้องการเข้าถึงบางครั้งอาจเป็นเรื่องยุ่งยาก

• สําหรับ Azure SQL ทรัพยากรคือhttps://database.windows.net
• สําหรับ Dataverse ทรัพยากรคือที่อยู่ https:// สําหรับสภาพแวดล้อมของคุณ ตัวอย่างเช่น: https://contoso.crm.dynamics.com

เข้าถึงโทเค็น API โดยใช้วิธี AuthenticationContext.AcquireTokenAsync

นี่คือตัวอย่างสําหรับการใส่ข้อมูลประจําตัวที่มีผลบังคับใช้ (ชื่อผู้ใช้) ด้วยโทเค็นการเข้าถึง

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

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

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

ด้วย Premium Per User (PPU)exportToFile API อนุญาตให้มีเพียงหนึ่งคําขอในหน้าต่างห้านาที คําขอหลายรายการภายในหน้าต่างห้านาทีส่งผลให้ เกิดข้อผิดพลาดคําขอ มากเกินไป (429)

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

API ของ Power BI SDK ที่ใช้ในตัวอย่างโค้ดสามารถดาวน์โหลดได้ที่นี่

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

1. ส่งคําขอการส่งออก
2. Polling
3. การรับไฟล์

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

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

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

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

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

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

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

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

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

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

1. ส่งคําขอการส่งออก
2. การโพลล์
3. การรับไฟล์

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

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

• การส่งออกรายงานที่มีการแบ่งหน้าที่มีแบบจําลองความหมายของ Power BI เป็นแหล่งข้อมูลไม่ได้รับการสนับสนุนในกรณีต่อไปนี้:

  • ผู้เรียกคือ โปรไฟล์บริการหลัก
  • หนึ่งในแหล่งข้อมูลของแบบจําลองความหมายถูกกําหนดค่าด้วยการเปิดใช้งานการลงชื่อเข้าระบบครั้งเดียว (SSO) และมีข้อมูลประจําตัวที่มีผลบังคับใช้ให้
  • แบบจําลองความหมายของ Power BI มี DirectQuery ไปยัง Azure Analysis Services หรือไปยังแบบจําลองความหมายอื่นของ Power BI และมีข้อมูลประจําตัวที่มีประสิทธิภาพให้

• การส่งออกรายงานที่มีการแบ่งหน้าที่มีแหล่งข้อมูล Azure Analysis Services ที่กําหนดค่าด้วยการเปิดใช้งานการลงชื่อเข้าระบบครั้งเดียว (SSO) ไม่ได้รับการสนับสนุนในกรณีต่อไปนี้:

  • ผู้เรียกคือ โปรไฟล์บริการหลัก
  • ผู้เรียกคือผู้ใช้หลักและมีการระบุข้อมูลประจําตัวที่มีผลบังคับใช้

• เมื่อต้องการส่งออกรายงานที่มีการแบ่งหน้าที่มีข้อมูลประจําตัวที่มีประสิทธิภาพ ชื่อผู้ใช้จะต้องเป็นผู้ใช้ที่มีอยู่จาก ID Microsoft Entra ของผู้เช่าของคุณ

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

• ไฮเปอร์ลิงก์ URL แชร์ไฟล์ (เส้นทางไฟล์แชร์ /UNC) ไม่ทํางานเมื่อส่งออกรายงานที่มีการแบ่งหน้าที่เผยแพร่บริการของ Power BI ออนไลน์

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

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

• ส่งออกรายงานไปยังไฟล์
• การฝังตัวสําหรับลูกค้าของคุณ
• การฝังตัวสําหรับองค์กรของคุณ