แชร์ผ่าน

ภาพรวมของแนวทางการรับรองความถูกต้องปริมาณงานใน Microsoft Fabric

  • บทความ

บทความนี้มีคําแนะนําเกี่ยวกับวิธีการทํางานกับการรับรองความถูกต้องเมื่อคุณกําลังสร้างปริมาณงาน Microsoft Fabric ซึ่งรวมถึงข้อมูลเกี่ยวกับการทํางานด้วยโทเค็นและการยินยอม

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

Data Plane และควบคุม API ของแผน

  • Data Plane APIs เป็น API ที่แบ็กเอนด์ปริมาณงานแสดงขึ้น Frontend ปริมาณงานสามารถเรียกพวกเขาได้โดยตรง สําหรับ DATA Plane API Backend ของปริมาณงานสามารถตัดสินใจว่า API ใดที่จะแสดง

  • ควบคุมแผน API คือ API ที่ผ่าน Fabric กระบวนการเริ่มต้นด้วย frontend ของปริมาณงานที่เรียกใช้ JavaScript API และสิ้นสุดด้วย Fabric ที่เรียก Backend ปริมาณงาน ตัวอย่างของ API ดังกล่าวคือ สร้างรายการ

    สําหรับควบคุม PLANe API ปริมาณงานต้องเป็นไปตามสัญญาที่กําหนดไว้ใน Backend ปริมาณงานและใช้ API เหล่านั้น

เปิดเผยแท็บ API บนแอปพลิเคชันของปริมาณงานใน Microsoft Entra ID

บนแท็บ แสดง API คุณจําเป็นต้องเพิ่มขอบเขตสําหรับควบคุม API ของแผนและขอบเขตสําหรับ API ของแผนข้อมูล:

  • ขอบเขตที่เพิ่มสําหรับควบคุม API ของแผนควรรับรองความถูกต้องสําหรับ Fabric Client สําหรับแอปพลิเคชันปริมาณงานที่มี ID แอปพลิเคชัน d2450708-699c-41e3-8077-b0c8341509aaไว้ล่วงหน้า ขอบเขตเหล่านั้นจะรวมอยู่ในโทเค็นที่ Backend ของปริมาณงานได้รับเมื่อ Fabric เรียกใช้งาน

    คุณจําเป็นต้องเพิ่มอย่างน้อยหนึ่งขอบเขตสําหรับ API เพลนของตัวควบคุมสําหรับโฟลว์ที่จะทํางาน

  • ขอบเขตที่เพิ่มสําหรับ API ของแผนข้อมูลควรตรวจสอบสิทธิ์ Microsoft Power BI ล่วงหน้าด้วย ID แอปพลิเคชัน 871c010f-5e61-4fb1-83ac-98610a7e9110 โดยจะรวมอยู่ในโทเค็นที่ acquireAccessToken JavaScript API ส่งกลับมา

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

    • ปริมาณงานจะแสดงสอง API ไปยังไคลเอ็นต์ ReadData และ WriteData
    • ปริมาณงานแสดงขอบเขตของแผนข้อมูลสองขอบเขต data.read และ data.write
    • ใน ReadData API ปริมาณงานจะตรวจสอบว่าขอบเขต data.read รวมอยู่ในโทเค็นก่อนที่จะดําเนินการต่อด้วยโฟลว์ เช่นเดียวกันกับ WriteData

แท็บสิทธิ์ API บนแอปพลิเคชันของปริมาณงานใน Microsoft Entra ID

บนแท็บ สิทธิ์ API คุณต้องเพิ่มขอบเขตทั้งหมดที่ปริมาณงานของคุณจําเป็นต้องแลกเปลี่ยนโทเค็น ขอบเขตที่บังคับในการเพิ่มจะถูก Fabric.Extend ภายใต้บริการของ Power BI คําขอไปยัง Fabric อาจล้มเหลวโดยไม่มีขอบเขตนี้

การทํางานกับโทเค็นและการยินยอม

เมื่อคุณกําลังทํางานกับ API ของแผนข้อมูล frontend ปริมาณงานจําเป็นต้องได้รับโทเค็นสําหรับการโทรไปยัง Backend ของปริมาณงาน

ส่วนต่อไปนี้อธิบายว่า frontend ของปริมาณงานควรใช้ JavaScript API และ ในนามของโฟลว์ (OBO) เพื่อรับโทเค็นสําหรับปริมาณงานและบริการภายนอก และเพื่อทํางานกับความยินยอม

ขั้นตอนที่ 1: รับโทเค็น

ปริมาณงานเริ่มต้นด้วยการขอโทเค็นโดยใช้ JavaScript API โดยไม่ต้องมีพารามิเตอร์ใด ๆ การเรียกใช้นี้อาจส่งผลให้เกิดสถานการณ์สองสถานการณ์:

  • ผู้ใช้เห็นหน้าต่างความยินยอมของการขึ้นต่อกันแบบคงที่ทั้งหมด (ที่มีการกําหนดค่าบนสิทธิ์ API แท็บ) ที่กําหนดค่าปริมาณงาน สถานการณ์นี้เกิดขึ้นถ้าผู้ใช้ไม่ใช่ส่วนหนึ่งของผู้เช่าหลักของแอปพลิเคชัน และผู้ใช้ไม่ได้ให้ความยินยอมกับ Microsoft Graph สําหรับแอปพลิเคชันนี้มาก่อน

  • ผู้ใช้ไม่เห็นหน้าต่างความยินยอม สถานการณ์นี้เกิดขึ้นถ้าผู้ใช้ให้ความยินยอมอย่างน้อยหนึ่งครั้งกับ Microsoft Graph สําหรับแอปพลิเคชันนี้ หรือถ้าผู้ใช้เป็นส่วนหนึ่งของผู้เช่าหลักของแอปพลิเคชัน

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

ขั้นตอนที่ 2: พยายามเข้าถึงบริการภายนอก

ปริมาณงานอาจจําเป็นต้องเข้าถึงบริการที่จําเป็นต้องมีการรับรองความถูกต้อง สําหรับการเข้าถึงนั้น จําเป็นต้องดําเนินการโฟลว์ OBOซึ่งจะแลกเปลี่ยนโทเค็นที่ได้รับจากไคลเอ็นต์หรือจาก Fabric ไปยังบริการอื่น การแลกเปลี่ยนโทเค็นอาจล้มเหลวเนื่องจากขาดความยินยอมหรือนโยบายการเข้าถึงแบบมีเงื่อนไขของ Microsoft Entra บางนโยบายที่มีการกําหนดค่าบนทรัพยากรที่ปริมาณงานกําลังพยายามแลกเปลี่ยนโทเค็น

ในการแก้ไขปัญหานี้ เป็นความรับผิดชอบของปริมาณงานในการเผยแพร่ข้อผิดพลาดไปยังลูกค้าเมื่อทํางานกับการโทรโดยตรงระหว่าง frontend และ Backend นอกจากนี้ยังเป็นความรับผิดชอบของปริมาณงานในการเผยแพร่ข้อผิดพลาดไปยังไคลเอ็นต์เมื่อทํางานกับการเรียกจาก Fabric โดยใช้การเผยแพร่ข้อผิดพลาดที่อธิบายไว้ใน การสื่อสารปริมาณงาน

หลังจากปริมาณงานเผยแพร่ข้อผิดพลาด แล้วจะสามารถเรียกใช้ acquireAccessToken JavaScript API เพื่อแก้ไขปัญหานโยบายการเข้าถึงตามเงื่อนไขหรือความยินยอม และลองดําเนินการอีกครั้ง

สําหรับความล้มเหลวของ DATA Plane API ดู การจัดการการรับรองความถูกต้องแบบหลายปัจจัย การเข้าถึงแบบมีเงื่อนไข และการยินยอมแบบเพิ่มหน่วย สําหรับควบคุมความล้มเหลวของ API ของเครื่องบิน โปรดดู การสื่อสารปริมาณงาน

สถานการณ์ตัวอย่าง

ลองมาดูปริมาณงานที่จําเป็นต้องเข้าถึง Fabric API สามตัว:

  • พื้นที่ทํางานรายการ: GET https://api.fabric.microsoft.com/v1/workspaces

  • สร้างคลังสินค้า: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

  • เขียนไปยังไฟล์ของเลคเฮ้าส์: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

เพื่อให้สามารถทํางานกับ API เหล่านั้น ได้ แบ็กเอนด์ปริมาณงานจําเป็นต้องแลกเปลี่ยนโทเค็นสําหรับขอบเขตต่อไปนี้:

  • สําหรับรายการพื้นที่ทํางาน: https://analysis.windows.net/powerbi/api/Workspace.Read.All หรือ https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
  • สําหรับการสร้างคลังสินค้า: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All หรือ https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
  • สําหรับการเขียนไฟล์ของเลคเฮ้าส์: https://storage.azure.com/user_impersonation

หมายเหตุ

คุณสามารถค้นหาขอบเขตที่จําเป็นสําหรับแต่ละ Fabric API ได้ใน บทความการอ้างอิงนี้

ขอบเขตที่กล่าวถึงก่อนหน้านี้จําเป็นต้องได้รับการกําหนดค่าในแอปพลิเคชันปริมาณงานภายใต้การอนุญาต API

ลองมาดูตัวอย่างของสถานการณ์ที่ปริมาณงานอาจพบ

ตัวอย่าง 1

สมมติว่า Backend ของปริมาณงานมี API ของแผนข้อมูลที่รับพื้นที่ทํางานของผู้ใช้และส่งกลับไปยังไคลเอ็นต์:

  1. frontend ของปริมาณงานจะถามโทเค็นโดยใช้ JavaScript API

  2. Frontend ของปริมาณงานจะเรียกใช้ API backend ของปริมาณงานเพื่อรับพื้นที่ทํางานของผู้ใช้ และแนบโทเค็นในคําขอ

  3. Backend ของปริมาณงานจะตรวจสอบโทเค็นและพยายามแลกเปลี่ยนสําหรับขอบเขตที่จําเป็น (สมมติว่า https://analysis.windows.net/powerbi/api/Workspace.Read.All)

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

  5. Backend ของปริมาณงานจะเผยแพร่ข้อผิดพลาดไปยัง frontend ของปริมาณงานโดยระบุว่าจําเป็นต้องได้รับความยินยอมสําหรับทรัพยากรนั้น Frontend ของปริมาณงานจะเรียกใช้ acquireAccessToken JavaScript API และให้ additionalScopesToConsent:

    workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

    อีกวิธีหนึ่งคือ ปริมาณงานสามารถตัดสินใจที่จะขอความยินยอมสําหรับการอ้างอิงแบบคงที่ทั้งหมดที่กําหนดค่าบนแอปพลิเคชัน ดังนั้นจึงเรียกใช้ JavaScript API และให้ promptFullConsent:

    workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

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

หมายเหตุ

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

ตัวอย่าง 2

สมมติว่า Backend ของปริมาณงานจําเป็นต้องเข้าถึง OneLake บนสร้างรายการ API (เรียกใช้จาก Fabric ไปยังปริมาณงาน):

  1. frontend ของปริมาณงานจะเรียกใช้ Create Item JavaScript API

  2. Backend ของปริมาณงานได้รับการเรียกใช้จาก Fabric และแยกโทเค็นที่ได้รับมอบหมายและตรวจสอบ

  3. ปริมาณงานพยายามที่จะแลกเปลี่ยนโทเค็นสําหรับ https://storage.azure.com/user_impersonation แต่ล้มเหลวเนื่องจากผู้ดูแลระบบผู้เช่าของการรับรองความถูกต้องแบบหลายปัจจัยที่กําหนดค่าโดยผู้ใช้ซึ่งจําเป็นต้องเข้าถึง Azure Storage (ดูรหัสข้อผิดพลาด AADSTS )

  4. ปริมาณงานจะเผยแพร่ข้อผิดพลาดควบคู่ไปกับการอ้างสิทธิ์ที่ส่งกลับในข้อผิดพลาดจาก Microsoft Entra ID ไปยังไคลเอ็นต์โดยใช้การเผยแพร่ข้อผิดพลาดที่อธิบายไว้ใน การสื่อสารเกี่ยวกับปริมาณงาน

  5. ส่วนหน้าของปริมาณงานจะเรียกใช้ acquireAccessToken JavaScript API และมีการอ้างสิทธิ์เป็น claimsForConditionalAccessPolicyซึ่ง claims หมายถึงการอ้างสิทธิ์ที่เผยแพร่จาก Backend ของปริมาณงาน:

    workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

หลังจากนั้น ปริมาณงานสามารถลองการดําเนินการอีกครั้งได้

การจัดการข้อผิดพลาดเมื่อร้องขอความยินยอม

ในบางครั้งผู้ใช้ไม่สามารถให้ความยินยอมเนื่องจากมีข้อผิดพลาดต่าง ๆ หลังจากการร้องขอความยินยอม การตอบกลับจะถูกส่งกลับไปยัง URI เปลี่ยนเส้นทาง ในตัวอย่างของเรา รหัสนี้รับผิดชอบในการจัดการการตอบสนอง (คุณสามารถค้นหาได้ในไฟล์ index.ts)

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
}

Frontend ของปริมาณงานสามารถแยกรหัสข้อผิดพลาดจาก URL และจัดการได้ตามนั้น

หมายเหตุ

ในทั้งสองสถานการณ์ (ข้อผิดพลาดและความสําเร็จ) ปริมาณงานต้องปิดหน้าต่างทันทีโดยไม่มีเวลาแฝง