ปรับปรุงการรีเฟรชด้วย Power BI REST API

คุณสามารถใช้ภาษาโปรแกรมใด ๆ ที่สนับสนุนการเรียก REST เพื่อทําการดําเนินการรีเฟรชแบบจําลองความหมาย โดยใช้ Power BI รีเฟรชชุดข้อมูล REST API

การรีเฟรชที่ดีที่สุดสําหรับแบบจําลองที่มีการแบ่งพาร์ติชันขนาดใหญ่และซับซ้อนจะถูกเรียกใช้แบบดั้งเดิมด้วยวิธีการเขียนโปรแกรมที่ใช้ TOM (Tabular Object Model), PowerShell cmdlets หรือ TMSL (Tabular Model Scripting Language) อย่างไรก็ตาม วิธีการเหล่านี้จําเป็นต้องใช้การเชื่อมต่อ HTTP ที่ใช้เวลานานซึ่งอาจไม่น่าเชื่อถือ

Power BI รีเฟรชชุดข้อมูล REST API สามารถดําเนินการรีเฟรชแบบจําลองแบบอะซิงโครนัส ดังนั้นการเชื่อมต่อ HTTP ที่ใช้เวลานานจากแอปพลิเคชันไคลเอ็นต์จึงไม่จําเป็น เมื่อเปรียบเทียบกับการดําเนินการรีเฟรชมาตรฐาน รีเฟรชขั้นสูงด้วย REST API มีตัวเลือกการกําหนดค่าเพิ่มเติมและคุณลักษณะต่อไปนี้ที่มีประโยชน์สําหรับแบบจําลองขนาดใหญ่:

• ยอมรับเป็นชุดงาน
• การรีเฟรชระดับตารางและพาร์ติชัน
• การใช้นโยบายการรีเฟรชแบบเพิ่มหน่วย
• รายละเอียดการรีเฟรช GET
• การยกเลิกการรีเฟรช
• การกําหนดค่าการหมดเวลา

โน้ต

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

URL พื้นฐาน

URL พื้นฐานอยู่ในรูปแบบต่อไปนี้:

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes 

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

ข้อกําหนด

คุณจําเป็นต้องมีข้อกําหนดต่อไปนี้เพื่อใช้ REST API:

• แบบจําลองความหมายใน Power BI Premium, Premium ต่อผู้ใช้ หรือ Power BI Embedded
• รหัสกลุ่มและรหัสชุดข้อมูลที่จะใช้ใน URL คําขอ
• Dataset.ReadWrite.All ขอบเขตสิทธิ์

จํานวนการรีเฟรชจะถูกจํากัดตามข้อจํากัดทั่วไปสําหรับการรีเฟรชตาม API สําหรับแบบจําลอง Pro และ Premium

ตรวจ สอบ

การเรียกใช้ทั้งหมดต้องรับรองความถูกต้องด้วยโทเค็น Microsoft Entra ID OAuth 2 ที่ถูกต้องในส่วนหัว Authorization โทเค็นต้องมีคุณสมบัติตรงตามข้อกําหนดต่อไปนี้:

• เป็นโทเค็นผู้ใช้หรือโครงร่างสําคัญของบริการแอปพลิเคชัน
• ให้ผู้ชมตั้งค่า เป็น https://api.powerbi.comอย่างถูกต้อง
• ผู้ใช้หรือแอปพลิเคชันที่มีสิทธิ์เพียงพอบนแบบจําลองจะใช้

โน้ต

การปรับเปลี่ยน REST API จะไม่เปลี่ยนแปลงสิทธิ์ที่กําหนดไว้ในปัจจุบันสําหรับการรีเฟรชแบบจําลอง

โพสต์/รีเฟรช

เมื่อต้องการทําการรีเฟรช ให้ใช้คํากริยา POST บนคอลเลกชัน /refreshes เพื่อเพิ่มวัตถุรีเฟรชใหม่ไปยังคอลเลกชัน ส่วนหัวของสถานที่เก็บในการตอบสนองรวมถึง requestIdด้วย เนื่องจากการดําเนินการเป็นแบบอะซิงโครนัส แอปพลิเคชันไคลเอ็นต์สามารถยกเลิกการเชื่อมต่อ และใช้ requestId เพื่อตรวจสอบสถานะในภายหลังถ้าจําเป็น

โค้ดต่อไปนี้แสดงตัวอย่างคําขอ:

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

เนื้อความคําขออาจคล้ายกับตัวอย่างต่อไปนี้:

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

โน้ต

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

พารามิเตอร์

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

ชื่อ	ประเภท	เริ่ม ต้น	คำอธิบาย
type	Enum	automatic	ชนิดของการประมวลผลที่จะดําเนินการ ชนิดที่สอดคล้องกับชนิดคําสั่งรีเฟรช TMSL: full, clearValues, calculate, dataOnly, automatic, และ defragment ไม่สนับสนุนชนิด add
commitMode	Enum	transactional	กําหนดว่าจะยอมรับออบเจ็กต์เป็นชุดงานหรือเฉพาะเมื่อเสร็จสมบูรณ์ โหมดจะถูก transactional และ partialBatch เมื่อใช้ partialBatch การดําเนินการรีเฟรชจะไม่เกิดขึ้นภายในหนึ่งธุรกรรม แต่ละคําสั่งจะกําหนดทีละรายการ ถ้ามีความล้มเหลว แบบจําลองอาจว่างเปล่าหรือรวมเฉพาะชุดย่อยของข้อมูล เพื่อป้องกันความล้มเหลวและเก็บข้อมูลที่อยู่ในแบบจําลองก่อนเริ่มการดําเนินการ ให้ดําเนินการ commitMode = transactional
maxParallelism	Int	10	กําหนดจํานวนสูงสุดของเธรดที่สามารถเรียกใช้คําสั่งประมวลผลแบบขนานได้ ค่านี้สอดคล้องกับคุณสมบัติ MaxParallelism ที่สามารถตั้งค่าได้ในคําสั่ง TMSL Sequence หรือโดยใช้วิธีการอื่น
retryCount	Int	0	จํานวนครั้งที่การดําเนินการลองใหม่ก่อนที่จะล้มเหลว
objects	อาร์เรย์	ทั้งแบบจําลอง	อาร์เรย์ของวัตถุที่จะประมวลผล วัตถุแต่ละรายการจะประกอบด้วย table เมื่อประมวลผลทั้งตาราง หรือ table และ partition เมื่อประมวลผลพาร์ติชัน ถ้าไม่มีการระบุวัตถุ แบบจําลองทั้งหมดจะรีเฟรช
applyRefreshPolicy	บูลีน	true	ถ้ามีการกําหนดนโยบายการรีเฟรชแบบเพิ่มหน่วย ให้กําหนดว่าจะใช้นโยบายหรือไม่ โหมดจะถูก true หรือ false ถ้าไม่มีการใช้นโยบาย กระบวนการแบบเต็มจะปล่อยให้ข้อกําหนดพาร์ติชันไม่เปลี่ยนแปลง และจะรีเฟรชพาร์ติชันทั้งหมดในตาราง ถ้า commitMode เป็น transactionalapplyRefreshPolicy สามารถ true หรือ falseได้ ถ้า commitMode ได้รับการ partialBatchapplyRefreshPolicy ของ true ไม่ได้รับการสนับสนุน และต้องตั้งค่า applyRefreshPolicy เป็น false
effectiveDate	วันที่	วันที่ปัจจุบัน	ถ้ามีการใช้นโยบายการรีเฟรชแบบเพิ่มหน่วย พารามิเตอร์ effectiveDate จะแทนที่วันที่ปัจจุบัน ถ้าไม่ได้ระบุ วันปัจจุบันจะถูกกําหนดโดยใช้การกําหนดค่าโซนเวลาภายใต้ 'รีเฟรช'
timeout	เชือก	05:00:00 (5 ชั่วโมง)	ถ้ามีการระบุ timeout แต่ละความพยายามในการรีเฟรชข้อมูลบนแบบจําลองความหมายจะเป็นไปตามการหมดเวลานั้น คําขอรีเฟรชเดียวอาจมีความพยายามหลายครั้งหากมีการระบุ retryCount ซึ่งอาจทําให้ระยะเวลาการรีเฟรชทั้งหมดเกินการหมดเวลาที่ระบุ ตัวอย่างเช่น การตั้งค่า timeout 1 ชั่วโมงด้วย retryCount 2 อาจส่งผลให้ระยะเวลาการรีเฟรชทั้งหมดนานถึง 3 ชั่วโมง ผู้ใช้สามารถปรับ timeout เพื่อย่อระยะเวลาการรีเฟรชสําหรับการตรวจหาความล้มเหลวที่เร็วขึ้นหรือขยายเกิน 5 ชั่วโมงค่าเริ่มต้นสําหรับการรีเฟรชข้อมูลที่ซับซ้อนมากขึ้น อย่างไรก็ตาม ระยะเวลาการรีเฟรชทั้งหมดรวมถึงการลองใหม่ต้องไม่เกิน 24 ชั่วโมง

การตอบสนอง

202 Accepted

การตอบสนองยังรวมถึง Location เขตข้อมูลส่วนหัวการตอบสนองเพื่อชี้ตัวเรียกไปยังการดําเนินการรีเฟรชที่สร้างขึ้นและยอมรับ Location คือตําแหน่งที่ตั้งของทรัพยากรใหม่ที่คําขอสร้างขึ้น ซึ่งรวมถึง requestId ที่การดําเนินการรีเฟรชขั้นสูงบางอย่างต้องการ ตัวอย่างเช่น ในการตอบสนองต่อไปนี้ requestId คือตัวระบุล่าสุดใน 87f31ef7-1e3a-4006-9b0b-191693e79e9eการตอบสนอง

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

รับ /รีเฟรช

ใช้คอลเลกชันรับคํากริยาบนคอลเลกชัน /refreshes เพื่อแสดงรายการการดําเนินการรีเฟรชในอดีต ปัจจุบัน และที่รอดําเนินการ

เนื้อหาคําตอบอาจมีลักษณะเหมือนกับตัวอย่างต่อไปนี้:

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

โน้ต

Power BI อาจปล่อยคําขอถ้ามีคําขอมากเกินไปในระยะเวลาอันสั้น Power BI ทําการรีเฟรช จัดคิวคําขอถัดไป และทิ้งคําขออื่น ๆ ทั้งหมด ตามการออกแบบ คุณไม่สามารถคิวรีสถานะในคําขอที่ทิ้งไปได้

คุณสมบัติการตอบสนอง

ชื่อ	ประเภท	คำอธิบาย
requestId	Guid	รหัสของคําขอรีเฟรช คุณจําเป็นต้องมี requestId เพื่อคิวรีสําหรับสถานะการดําเนินการรีเฟรชแต่ละรายการ หรือยกเลิกการดําเนินการรีเฟรชที่กําลังดําเนินการอยู่
refreshType	เชือก	OnDemand ระบุว่าการรีเฟรชถูกทริกเกอร์แบบโต้ตอบผ่านพอร์ทัล Power BI Scheduled ระบุว่ากําหนดการรีเฟรชแบบจําลองทริกเกอร์การรีเฟรช ViaApi ระบุว่าการเรียกใช้ API ทริกเกอร์การรีเฟรช ViaEnhancedApi ระบุว่าการเรียกใช้ API ทริกเกอร์การรีเฟรชขั้นสูงแล้ว
startTime	เชือก	วันที่และเวลาของการรีเฟรชเริ่มต้น
endTime	เชือก	วันที่และเวลาของการรีเฟรชสิ้นสุด
status	เชือก	Completed ระบุว่าการดําเนินการรีเฟรชเสร็จสมบูรณ์แล้ว Failed ระบุว่าการดําเนินการรีเฟรชล้มเหลว Unknown ระบุว่าไม่สามารถกําหนดสถานะความสมบูรณ์ได้ ด้วยสถานะนี้ endTime จะว่างเปล่า Disabled ระบุว่าการรีเฟรชถูกปิดใช้งานโดยการรีเฟรชที่เลือก Cancelled ระบุว่าการรีเฟรชถูกยกเลิกเรียบร้อยแล้ว
extendedStatus	เชือก	เพิ่มคุณสมบัติ status เพื่อให้ข้อมูลเพิ่มเติม

โน้ต

ใน Azure Analysis Services ผลลัพธ์ status ที่เสร็จสมบูรณ์คือ succeeded ถ้าคุณย้ายโซลูชัน Azure Analysis Services ไปยัง Power BI คุณอาจต้องปรับเปลี่ยนโซลูชันของคุณ

จํากัดจํานวนของการดําเนินการรีเฟรชที่ส่งกลับ

Power BI REST API รองรับการจํากัดจํานวนรายการที่ร้องขอในประวัติการรีเฟรชโดยใช้พารามิเตอร์ $top ทางเลือก ถ้าไม่ได้ระบุ ค่าเริ่มต้นคือรายการที่พร้อมใช้งานทั้งหมด

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}      

รับ /รีเฟรช/<requestId>

เมื่อต้องการตรวจสอบสถานะของการดําเนินการรีเฟรช ให้ใช้ รับคํากริยา บนวัตถุรีเฟรชโดยการระบุ requestId ถ้าการดําเนินการอยู่ในระหว่างดําเนินการ status จะแสดง InProgressดังในตัวอย่างเนื้อหาการตอบสนองต่อไปนี้:

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

ลบ /รีเฟรช/<requestId>

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

เช่น

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

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

การดําเนินการรีเฟรชมีข้อควรพิจารณาและข้อจํากัดดังต่อไปนี้:

การดําเนินการรีเฟรชมาตรฐาน

• คุณไม่สามารถยกเลิกการรีเฟรชแบบจําลองตามกําหนดการหรือตามคําขอที่ถูกทริกเกอร์โดยการเลือกปุ่มรีเฟรชในพอร์ทัลโดยใช้ DELETE /refreshes/<requestId>
• การรีเฟรชแบบจําลองตามกําหนดการและตามความต้องการที่ถูกทริกเกอร์โดยการเลือกปุ่มรีเฟรชในพอร์ทัลไม่สนับสนุนการรับรายละเอียดการดําเนินการรีเฟรชโดยใช้ GET /refreshes/<requestId>
• รับรายละเอียดและยกเลิกเป็นการดําเนินการใหม่สําหรับรีเฟรชที่ได้รับการปรับปรุงเท่านั้น การรีเฟรชมาตรฐานไม่สนับสนุนการดําเนินการเหล่านี้

Power BI Embedded

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

การลดข้อมูลแบบจําลองความหมาย

Power BI ใช้การจัดการหน่วยความจําแบบไดนามิกเพื่อปรับหน่วยความจําความจุให้เหมาะสม ถ้ามีการขับแบบจําลองจากหน่วยความจําระหว่างการดําเนินการรีเฟรช ข้อผิดพลาดต่อไปนี้อาจส่งกลับ:

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

โซลูชันคือการเรียกใช้การดําเนินการรีเฟรชใหม่ เมื่อต้องการเรียนรู้เพิ่มเติมเกี่ยวกับการจัดการหน่วยความจําแบบไดนามิกและการลดข้อมูลแบบจําลอง โปรดดู การลดข้อมูลแบบจําลอง

ขีดจํากัดเวลาการดําเนินการรีเฟรช

การรีเฟรชอาจมีความพยายามหลายครั้งถ้ามีการระบุ retryCount ความพยายามแต่ละครั้งจะมีการหมดเวลาเริ่มต้น 5 ชั่วโมง ซึ่งสามารถปรับได้โดยใช้พารามิเตอร์ timeout ระยะเวลาการรีเฟรชรวม รวมถึงการลองใหม่ต้องไม่เกิน 24 ชั่วโมง

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

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

เมื่อวางแผนการรีเฟรชแบบจําลองความหมายของคุณด้วยรีเฟรชชุดข้อมูล REST API ให้พิจารณาขีดจํากัดเวลาและพารามิเตอร์ retryCount การรีเฟรชอาจเกินการหมดเวลาหากความพยายามเริ่มต้นล้มเหลว และลองทําซ้ําถูกตั้งค่าเป็น 1 หรือมากกว่า ถ้าคุณร้องขอการรีเฟรชด้วย "retryCount": 1 และการพยายามครั้งแรกจะล้มเหลวหลังจาก 4 ชั่วโมง ความพยายามครั้งที่สองจะเริ่มขึ้น ถ้าการดําเนินการนี้สําเร็จใน 3 ชั่วโมง เวลาทั้งหมดสําหรับการรีเฟรชคือ 7 ชั่วโมง

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

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

สําหรับตัวอย่างโค้ด C# เพื่อให้คุณเริ่มต้น ดู RestApiSample บน GitHub

หากต้องการใช้ตัวอย่างโค้ด:

1. ลอกแบบหรือดาวน์โหลด repo
2. เปิดโซลูชัน RestApiSample
3. ค้นหาบรรทัด และใส่URL ฐานของ ของคุณ

ตัวอย่างโค้ดใช้การรับรองความถูกต้องของบริการหลัก

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

• REST API ของชุดข้อมูลการรีเฟรช Power BI
• ใช้ Power BI REST API