หมายเหตุ
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลอง ลงชื่อเข้าใช้หรือเปลี่ยนไดเรกทอรีได้
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลองเปลี่ยนไดเรกทอรีได้
บทนำ
บทความนี้ช่วยให้คุณเข้าใจและแก้ไขปัญหาข้อผิดพลาดทั่วไปที่ส่งกลับโดย Microsoft Fabric REST API อธิบายรูปแบบข้อผิดพลาดมาตรฐานที่ใช้โดยบริการ และให้คําแนะนําในการแก้ไขรหัสสถานะ HTTP ที่พบบ่อยที่สุด
ทําความเข้าใจการตอบสนองข้อผิดพลาดของ Microsoft Fabric
เมื่อมีข้อผิดพลาดเกิดขึ้นขณะประมวลผลการร้องขอไปยัง Microsoft Fabric REST API บริการจะส่งกลับวัตถุมาตรฐาน ErrorResponse ในเนื้อหาการตอบสนอง
เมื่อแก้ไขปัญหา ให้บันทึกและบันทึก requestIdเสมอ เนื่องจากจะระบุคําขอโดยไม่ซ้ํากันและจําเป็นเมื่อติดต่อฝ่ายสนับสนุนของ Microsoft รหัสคําขอจะพร้อมใช้งานทั้งในเนื้อหาการตอบกลับและในส่วนหัวของการตอบกลับ
สำคัญ
errorCodeค่ามีเสถียรภาพและอิงตามสัญญา- ข้อความที่มนุษย์อ่านได้
messageอาจเปลี่ยนแปลงเมื่อเวลาผ่านไป และไม่ควรแยกวิเคราะห์โดยทางโปรแกรม
สคีมา ErrorResponse
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
errorCode |
string |
ตัวระบุที่เสถียรสําหรับเงื่อนไขข้อผิดพลาด ใช้ค่านี้เมื่อใช้ตรรกะการจัดการข้อผิดพลาด |
message |
string |
คําอธิบายข้อผิดพลาดที่มนุษย์อ่านได้ |
moreDetails |
ErrorResponseDetails[] |
รายการรายละเอียดข้อผิดพลาดเพิ่มเติมเพิ่มเติม |
relatedResource |
ErrorRelatedResource |
ข้อมูลเกี่ยวกับทรัพยากรที่เกี่ยวข้องกับข้อผิดพลาด (หากมี) |
requestId |
string |
ตัวระบุเฉพาะของคําขอที่ล้มเหลว รวมค่านี้เมื่อติดต่อฝ่ายสนับสนุนของ Microsoft |
สคีมา ErrorResponseDetails
ให้บริบทเพิ่มเติมสําหรับสถานการณ์ข้อผิดพลาดที่ซับซ้อน
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
errorCode |
string |
ตัวระบุที่เสถียรซึ่งอธิบายรายละเอียดข้อผิดพลาดเฉพาะ |
message |
string |
คําอธิบายรายละเอียดข้อผิดพลาดที่มนุษย์อ่านได้ |
relatedResource |
ErrorRelatedResource |
ทรัพยากรที่เกี่ยวข้องกับรายละเอียดข้อผิดพลาดเฉพาะนี้ |
สคีมา ErrorRelatedResource
ระบุรีซอร์สที่เกี่ยวข้องกับข้อผิดพลาด
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
resourceId |
string |
รหัสของทรัพยากรที่เกี่ยวข้องกับข้อผิดพลาด |
resourceType |
string |
ชนิดของทรัพยากร (ตัวอย่างเช่น พื้นที่ทํางาน สินค้า หรือความจุ) |
สถานการณ์ข้อผิดพลาด HTTP ทั่วไป
ส่วนต่อไปนี้อธิบายรหัสสถานะ HTTP ทั่วไปที่ส่งคืนโดย Microsoft Fabric REST API พร้อมกับสาเหตุหลักทั่วไปและวิธีแก้ปัญหาที่แนะนํา
API ส่งคืน 401 – ไม่ได้รับอนุญาต
การตอบกลับ 401 บ่งชี้ว่าคําขอล้มเหลวในระหว่างการตรวจสอบความถูกต้องหรือการตรวจสอบโทเค็นการเข้าถึง
สาเหตุที่พบบ่อย
| รหัสข้อผิดพลาด | คำอธิบาย | การแก้ปัญหา |
|---|---|---|
TokenExpired |
โทเค็นเพื่อการเข้าถึงหมดอายุแล้ว | รับโทเค็นเพื่อการเข้าถึงใหม่และลองคําขออีกครั้ง |
InsufficientScopes |
โทเค็นเพื่อการเข้าถึงไม่มีขอบเขตที่จําเป็น | อัปเดตแอปพลิเคชันเพื่อร้องขอขอบเขตที่จําเป็นตามที่ระบุไว้ในข้อกําหนด API หรืออัปเดตการลงทะเบียนแอปพลิเคชัน Microsoft Entra |
API ส่งคืน 403 – ต้องห้าม
การตอบกลับ 403 บ่งชี้ว่าผู้เรียกได้รับการรับรองความถูกต้อง แต่ไม่มีสิทธิ์เพียงพอที่จะดําเนินการตามที่ร้องขอบนทรัพยากรเป้าหมาย
สาเหตุที่พบบ่อย
| รหัสข้อผิดพลาด | คำอธิบาย | การแก้ปัญหา |
|---|---|---|
InsufficientPrivileges |
ผู้เรียกไม่มีสิทธิ์ที่จําเป็นในการเข้าถึงทรัพยากร | ขอให้ผู้ดูแลระบบพื้นที่ทํางานหรือทรัพยากรให้สิทธิ์ที่เพียงพอแก่ผู้ใช้ที่เรียกหรือบริการหลัก |
API ส่งคืน 404 – ไม่พบ
การตอบกลับ 404 บ่งชี้ว่าไม่มีทรัพยากรที่ร้องขอหรืออ้างอิงหรือผู้โทรไม่สามารถเข้าถึงได้
บันทึกย่อ
API แต่ละรายการอาจกําหนดรหัสข้อผิดพลาดเฉพาะ API เพิ่มเติม โปรดดูข้อกําหนด API เสมอสําหรับรายละเอียดที่เชื่อถือได้
สาเหตุที่พบบ่อย
| รหัสข้อผิดพลาด | คำอธิบาย | การแก้ปัญหา |
|---|---|---|
WorkspaceNotFound |
ไม่พบพื้นที่ทํางานที่ระบุ | ตรวจสอบว่ามีการระบุรหัสออบเจ็กต์พื้นที่ทํางานที่ถูกต้อง |
EntityNotFound |
ไม่พบทรัพยากรที่ร้องขอ | ยืนยันว่าได้ระบุรหัสทรัพยากรที่ถูกต้อง เอนทิตีที่หายไปจะถูกระบุใน relatedResource ฟิลด์ของการตอบสนองข้อผิดพลาด |
API ส่งคืน 429 – คําขอมากเกินไป
การตอบกลับ 429 บ่งชี้ว่าคําขอถูกควบคุม Microsoft Fabric ส่งกลับรหัสสถานะ 429 ด้วยเหตุผลที่แตกต่างกันสองประการ โดยแต่ละเหตุผลจะระบุโดยความแตกต่างerrorCodeในเนื้อหาการตอบกลับ
สาเหตุที่พบบ่อย
| รหัสข้อผิดพลาด | คำอธิบาย | การแก้ปัญหา |
|---|---|---|
RequestBlocked |
อัตราการร้องขอเกินขีดจํากัดการควบคุมของบริการ | รอตามระยะเวลาที่ระบุในส่วน Retry-After หัวก่อนที่จะลองอีกครั้ง ดูจัดการการจํากัดอัตราในแอปพลิเคชันของคุณ |
CapacityLimitExceeded |
การประมวลผล (หน่วยความจุ) ที่ใช้ในความจุของคุณเกินขีดจํากัดของ Fabric SKU ที่ซื้อ | ลองคําขออีกครั้งในภายหลัง ดู การควบคุมปริมาณความจุของมือจัดการ |
การจํากัดอัตรา (RequestBlocked)
RequestBlockedข้อผิดพลาดบ่งชี้ว่าอัตราการร้องขอเกินขีดจํากัดการควบคุมของบริการ
- การควบคุมปริมาณจะถูกบังคับใช้ตามข้อมูลประจําตัวของผู้โทร
- โดยทั่วไปขีดจํากัดอัตราจะได้รับการประเมินในช่วงเวลาหนึ่งนาที
ลองข้อมูลเวลาอีกครั้ง
เมื่อมีการจํากัดอัตรา จะมีการระบุข้อมูลการลองใหม่ในสองตําแหน่ง:
เนื้อหาการตอบสนอง (
message)
ตัวอย่าง:
"Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"Retry-Afterส่วนหัวการตอบกลับ HTTP
ระบุจํานวนวินาทีที่ไคลเอ็นต์ต้องรอก่อนที่จะลองอีกครั้ง
ชอบส่วน Retry-After หัวเสมอเมื่อใช้ตรรกะการลองใหม่
จัดการการจํากัดอัตราในแอปพลิเคชันของคุณ
การใช้งานควร:
- ตรวจหาการตอบกลับ HTTP 429
- แยกวิเคราะห์และให้เกียรติ
Retry-Afterส่วนหัว - ใช้นโยบายการลองใหม่แบบมีขอบเขต เช่น การย้อนกลับแบบเอ็กซ์โพเนนเชียลพร้อมความกระวนกระวายใจสําหรับสถานการณ์ขนาดใหญ่
- หลีกเลี่ยงการลองซ้ําแบบไม่มีที่สิ้นสุด
ลดโอกาสในการจํากัดอัตรา
- ใช้การดําเนินการจํานวนมากและชุดงาน เมื่อพร้อมใช้งาน
- ต้องการรายการ API มากกว่าคําขอทรัพยากรเดียวซ้ําๆ
- แคชข้อมูลที่เข้าถึงบ่อย โดยเฉพาะข้อมูลเมตาที่มีการเปลี่ยนแปลงไม่บ่อยนัก
- หลีกเลี่ยงการเข้าชมอย่างรวดเร็ว โดยการกระจายคําขออย่างเท่าเทียมกันเมื่อเวลาผ่านไป
เกินขีดจํากัดความจุ (CapacityLimitExceeded)
CapacityLimitExceededข้อผิดพลาดบ่งชี้ว่าการประมวลผล (หน่วยความจุ) ที่ใช้ในความจุของคุณเกินขีดจํากัดของ Fabric SKU ที่ซื้อ การควบคุมปริมาณนี้ไม่ได้เกิดจากจํานวนการเรียก API ที่ผู้โทรรายใดรายหนึ่งทํา ซึ่งสะท้อนถึงการประมวลผลโดยรวมที่ใช้ในปริมาณงานทั้งหมดในความจุ
ตัวอย่างเนื้อหาการตอบกลับ:
"Your organization's Fabric compute capacity has exceeded its limits. Try again later."
จัดการการควบคุมปริมาณความจุ
เนื่องจากการควบคุมนี้ขึ้นอยู่กับการประมวลผลโดยรวมที่ใช้ในความจุของคุณมากกว่าอัตราคําขอแต่ละรายการ ส่วนหัวจึง Retry-After ไม่สามารถใช้ได้ และการลองใหม่ทันทีไม่น่าจะสําเร็จจนกว่าการใช้การประมวลผลของความจุจะกลับเข้ามาภายในขีดจํากัด การใช้งานควร:
- ลองคําขออีกครั้งในภายหลังโดยใช้นโยบายการลองใหม่ที่มีขอบเขตที่มีการย้อนกลับแบบเอ็กซ์โพเนนเชียล
- หากข้อผิดพลาดยังคงอยู่ ให้พิจารณาเพิ่มหรือขยายความจุ Fabric ของคุณ
สําหรับข้อมูลเพิ่มเติมเกี่ยวกับหน่วยความจุ SKU และวิธีการใช้ความจุ Fabric โปรดดู วางแผนขนาดความจุของคุณ
Summary
การสร้างการผสานรวมที่เชื่อถือได้กับ Microsoft Fabric REST API จําเป็นต้องมีการจัดการข้อผิดพลาดที่มีประสิทธิภาพและรูปแบบคําขอที่มีประสิทธิภาพ ด้วยการทําความเข้าใจการตอบสนองข้อผิดพลาด ให้เกียรติสัญญาณการควบคุมปริมาณ และปรับรูปแบบคําขอให้เหมาะสม คุณจะสามารถสร้างแอปพลิเคชันที่ยืดหยุ่นได้
เนื้อหาที่เกี่ยวข้อง
สําหรับคําถามเพิ่มเติมหรือคําแนะนําของชุมชน โปรดดู ชุมชน Microsoft Fabric