ปรับปรุงการรีเฟรชด้วย 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 พื้นฐานตามพารามิเตอร์ได้ ในไดอะแกรมต่อไปนี้ กลุ่ม ชุดข้อมูล และการรีเฟรชคือคอลเลกชัน กลุ่ม ชุดข้อมูล และการรีเฟรชเป็นวัตถุ

Diagram that shows asynchronous refresh flow.

ข้อกำหนด

คุณจําเป็นต้องมีข้อกําหนดต่อไปนี้เพื่อใช้ 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,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

หมายเหตุ

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

พารามิเตอร์

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

ชื่อ ขนิด ค่าเริ่มต้น คำอธิบาย
type Enum automatic ชนิดของการประมวลผลที่จะดําเนินการ ชนิด ที่สอดคล้องกับชนิดคําสั่งรีเฟรช TMSL: full, clearValuescalculate, 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 เป็น partialBatchapplyRefreshPolicytrue ไม่ได้รับการสนับสนุน และapplyRefreshPolicyต้องตั้งค่าเป็นfalse
effectiveDate วันที่ วันที่ปัจจุบัน ถ้ามีการใช้นโยบายการรีเฟรชแบบเพิ่มหน่วย พารามิเตอร์จะ effectiveDate แทนที่วันที่ปัจจุบัน ถ้าไม่ได้ระบุ UTC จะถูกใช้เพื่อกําหนดวันปัจจุบัน

Response

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",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "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"
        }
    ]
}

ลบ /refreshes/<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 แบบฝังตัว

หากความจุถูกหยุดชั่วคราวด้วยตนเองในพอร์ทัล 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 ไม่ได้ระบุหรือระบุเป็น 0 (ค่าเริ่มต้น) ในเนื้อความของคําขอ ข้อผิดพลาดการหมดเวลาจะแสดง

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

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

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

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

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

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

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

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

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

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