ส่งออกรายงานที่มีการแบ่งหน้าไปยังไฟล์
API exportToFile
เปิดใช้งานการส่งออกรายงานที่มีการแบ่งหน้าของ 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 เหตุการณ์ "การแสดงผล" และเริ่มต้นการส่งออกเมื่อการแสดงผลเสร็จสิ้นเท่านั้น
การโพลล์
API เป็นแบบอะซิงโครนัส เมื่อมีการเรียกใช้ exportToFile API จะทริกเกอร์งานการส่งออก หลังจากทริกเกอร์งานส่งออก ให้ใช้ การโพลล์ เพื่อติดตามงานจนกว่าจะเสร็จสมบูรณ์
เมื่อการส่งออกเสร็จสมบูรณ์ การเรียกใช้ 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)
ตัวอย่างรหัส
Power BI API SDK ที่ใช้ในตัวอย่างโค้ดสามารถดาวน์โหลด ที่นี่
เมื่อคุณสร้างงานส่งออก มีสามขั้นตอนที่ต้องปฏิบัติตาม:
- ส่งคําขอการส่งออก
- การโพลล์
- การรับไฟล์
ส่วนนี้มีตัวอย่างสําหรับแต่ละขั้นตอน
ขั้นตอนที่ 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 สําหรับการส่งออกรายงาน ตัวอย่างนี้ประกอบด้วยขั้นตอนต่อไปนี้:
- ส่งคําขอส่งออก
- การโพลล์
- รับไฟล์
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 ออนไลน์
เนื้อหาที่เกี่ยวข้อง
ตรวจสอบวิธีการฝังเนื้อหาสําหรับลูกค้าและองค์กรของคุณ: