ใช้ Backend ของ Microsoft Fabric

บทความ
05/21/2024

ที่เก็บตัวอย่างการพัฒนาปริมาณงาน Microsoft Fabric นี้เป็นจุดเริ่มต้นสําหรับการสร้างแอปพลิเคชันที่จําเป็นต้องรวมกับบริการต่าง ๆ และสําหรับการรวมกับสถาปัตยกรรมของ lakehouse บทความนี้ช่วยให้คุณตั้งค่าสภาพแวดล้อม และกําหนดค่าคอมโพเนนต์ที่จําเป็นเพื่อเริ่มต้นใช้งาน บทความนี้สรุปคอมโพเนนต์หลักและบทบาทของพวกเขาในสถาปัตยกรรม

Frontend

Frontend คือที่ที่คุณจัดการประสบการณ์ของผู้ใช้ (UX) และลักษณะการทํางาน ซึ่งจะสื่อสารกับพอร์ทัล Fabric frontend ผ่าน iFrame เพื่ออํานวยความสะดวกในการโต้ตอบแบบไร้รอยต่อ

สําหรับข้อมูลเพิ่มเติม โปรดดู frontend ของ Microsoft Fabric Workload Development Kit

Backend

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

Azure Relay และ DevGateway

Azure Relay ช่วยให้การสื่อสารระหว่างสภาพแวดล้อมการพัฒนาในเครื่องและ Fabric Backend ในโหมดนักพัฒนา ในโหมดนักพัฒนา ปริมาณงานจะดําเนินการบนเครื่องของนักพัฒนา

ยูทิลิตี้ DevGateway มีสองบทบาท:

ซึ่งจัดการด้านปริมาณงานของช่องทาง Azure Relay และจัดการการลงทะเบียนของอินสแตนซ์ภายในปริมาณงานด้วย Fabric ในบริบทของพื้นที่ทํางานเฉพาะ ยูทิลิตี้จัดการการแจกแจงเมื่อยกเลิกการเชื่อมต่อช่อง
ทํางานร่วมกับ Azure Relay เพื่อเรียกใช้ API ปริมาณงานช่องจาก Fabric ไปยังปริมาณงาน

ปริมาณงานควบคุมการเรียกใช้ API จะทําโดยตรงจากปริมาณงานไปยัง Fabric ช่อง Azure Relay ไม่จําเป็นสําหรับการโทร

การรวมเลคเฮ้าส์

สถาปัตยกรรมชุดการพัฒนาปริมาณงานรวมเข้ากับสถาปัตยกรรมของเลคเฮ้าส์ได้อย่างราบรื่นสําหรับการดําเนินงาน เช่น การบันทึก การอ่าน และการดึงข้อมูล การโต้ตอบจะอํานวยความสะดวกผ่าน Azure Relay และ Fabric SDK เพื่อช่วยในการสื่อสารที่ปลอดภัยและได้รับการรับรอง สําหรับข้อมูลเพิ่มเติม ดู การทํางานกับข้อมูลลูกค้า

การรับรองความถูกต้องและการรักษาความปลอดภัย

Microsoft Entra ID ใช้สําหรับการรับรองความถูกต้องที่ปลอดภัย ตรวจสอบให้แน่ใจว่าการโต้ตอบทั้งหมดภายในสถาปัตยกรรมได้รับอนุญาตและปลอดภัย

ภาพรวมชุดการพัฒนาแสดงภาพรวมเกี่ยวกับสถาปัตยกรรมของเรา สําหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีกําหนดค่าโครงการ สําหรับแนวทางการรับรองความถูกต้อง และเพื่อเริ่มต้นใช้งาน ให้ดูบทความต่อไปนี้:

แผนภาพที่แสดงว่า Fabric SDK รวมเข้ากับ Fabric อย่างไร

Frontend สร้างการสื่อสารกับพอร์ทัล Fabric frontend ผ่าน iFrame พอร์ทัลจะโต้ตอบกับแบ็กเอนด์ Fabric โดยการเรียกใช้ API สาธารณะที่ถูกเปิดเผย

สําหรับการโต้ตอบระหว่างกล่องการพัฒนาแบ็กเอนด์และแบ็กเอนด์ Fabric นั้น Azure Relay ทําหน้าที่เป็นท่อ นอกจากนี้กล่องพัฒนาแบ็กเอนด์ยังรวมกับเลคเฮ้าส์ได้อย่างราบรื่น การสื่อสารได้รับการอํานวยความสะดวกโดยใช้ Azure Relay และ Fabric Software Development Kit (SDK) ที่ติดตั้งอยู่บนกล่องการพัฒนา Backend

การรับรองความถูกต้องของการสื่อสารทั้งหมดภายในคอมโพเนนต์เหล่านี้ได้รับการยืนยันผ่าน Microsoft Entra Microsoft Entra มีสภาพแวดล้อมที่ปลอดภัยและได้รับการรับรองสําหรับการโต้ตอบระหว่าง frontend, backend, Azure Relay, Fabric SDK และ Lakehouse

ข้อกำหนดเบื้องต้น

.NET 7.0 SDK
Visual Studio 2022

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

การจัดการแพคเกจ NuGet

<NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile> และ <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>: คุณสมบัติเหล่านี้ระบุเส้นทางไปยังไฟล์ NuSpec ที่ใช้สําหรับการสร้างแพคเกจ NuGet สําหรับโหมดดีบักและรุ่น ไฟล์ NuSpec ประกอบด้วยเมตาดาต้าเกี่ยวกับแพคเกจ เช่น ID เวอร์ชัน การขึ้นต่อกัน และข้อมูลอื่น ๆ ที่เกี่ยวข้อง
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>: เมื่อตั้งค่าเป็น trueคุณสมบัตินี้จะแนะนํากระบวนการสร้างเพื่อสร้างแพคเกจ NuGet โดยอัตโนมัติระหว่างแต่ละรุ่น คุณสมบัตินี้มีประโยชน์เพื่อให้แน่ใจว่าแพ็คเกจอัปเดตอยู่เสมอด้วยการเปลี่ยนแปลงล่าสุดในโครงการ
<IsPackable>true</IsPackable>: เมื่อตั้งค่าเป็น trueคุณสมบัตินี้จะระบุว่าโครงการสามารถรวมเป็นแพคเกจ NuGet ได้ การบรรจุเป็นคุณสมบัติที่จําเป็นสําหรับโครงการที่มีวัตถุประสงค์เพื่อสร้างแพคเกจ NuGet ในระหว่างกระบวนการสร้าง

แพคเกจ NuGet ที่สร้างขึ้นสําหรับโหมดดีบักจะอยู่ใน src\bin\Debug directory หลังจากกระบวนการสร้าง

เมื่อคุณทํางานในโหมดคลาวด์ คุณสามารถเปลี่ยนการกําหนดค่ารุ่น Visual Studio เป็น เผยแพร่ และสร้างแพคเกจของคุณ แพคเกจที่สร้างขึ้นจะอยู่ใน src\bin\Release ไดเรกทอรี สําหรับข้อมูลเพิ่มเติม ดู คู่มือการทํางานในโหมดคลาวด์

การขึ้นต่อกัน

ตัวอย่าง Backend หม้อน้ําขึ้นอยู่กับแพคเกจ Azure SDK ต่อไปนี้:
- Azure.Core
- Azure.Identity
- Azure.Storage.Files.DataLake
- แพคเกจข้อมูลประจําตัวของ Microsoft

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

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
    <BuildDependsOn>PreBuild</BuildDependsOn>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <IsPackable>true</IsPackable>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Azure.Core" Version="1.38.0" />
    <PackageReference Include="Azure.Identity" Version="1.11.0" />
    <PackageReference Include="Azure.Storage.Files.DataLake" Version="12.14.0" />
    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.9" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="7.0.5" />
    <PackageReference Include="Microsoft.Extensions.Logging.Debug" Version="7.0.0" />
    <PackageReference Include="Microsoft.Identity.Client" Version="4.60.3" />
    <PackageReference Include="Microsoft.IdentityModel.Protocols" Version="6.30.1" />
    <PackageReference Include="Microsoft.IdentityModel.Protocols.OpenIdConnect" Version="6.30.1" />
    <PackageReference Include="Microsoft.IdentityModel.Tokens" Version="6.30.1" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
  </ItemGroup>

  <ItemGroup>
    <Folder Include="Properties\ServiceDependencies\" />
  </ItemGroup>

  <Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\RemoveErrorFile.ps1 -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ManifestValidator.ps1 -inputDirectory .\Packages\manifest\ -inputXml WorkloadManifest.xml -inputXsd WorkloadDefinition.xsd -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ItemManifestValidator.ps1 -inputDirectory .\Packages\manifest\ -inputXsd ItemDefinition.xsd -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ValidateNoDefaults.ps1 -outputDirectory ValidationScripts\" />
    <Error Condition="Exists('ValidationScripts\ValidationErrors.txt')" Text="Validation errors with either manifests or default values" File="ValidationScripts\ValidationErrors.txt" />
  </Target>

</Project>

เริ่มต้นใช้งาน

เมื่อต้องการตั้งค่าโครงการตัวอย่างปริมาณงานบนเครื่องเฉพาะที่ของคุณ:

โคลนที่เก็บ: เรียกใช้git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample.git
ใน Visual Studio 2022 เปิดโซลูชัน
ตั้งค่าการลงทะเบียนแอปโดยทําตามคําแนะนําใน บทช่วยสอนการรับรองความถูกต้อง ตรวจสอบให้แน่ใจว่าทั้งโครงการ frontend และ Backend ของคุณมีการตั้งค่าที่จําเป็นซึ่งอธิบายไว้ในบทความ Microsoft Entra ใช้สําหรับการรับรองความถูกต้องที่ปลอดภัยเพื่อช่วยให้แน่ใจว่าการโต้ตอบทั้งหมดภายในสถาปัตยกรรมได้รับอนุญาตและปลอดภัย
อัปเดต URL พื้นฐาน Microsoft OneLake DFS ขึ้นอยู่กับสภาพแวดล้อม Fabric ของคุณ คุณอาจสามารถอัปเดตค่าสําหรับ OneLakeDFSBaseURL ใน โฟลเดอร์ src\Constants ได้ ค่าเริ่มต้นคือ onelake.dfs.fabric.microsoft.comแต่คุณสามารถอัปเดต URL เพื่อแสดงสภาพแวดล้อมของคุณได้ สําหรับข้อมูลเพิ่มเติมเกี่ยวกับเส้นทาง DFS ให้ดูเอกสาร ประกอบ OneLake
ตั้งค่าการกําหนดค่าปริมาณงาน
1. คัดลอก workload-dev-mode.json จาก src/Config ไปยัง C:
2. ใน ไฟล์ workload-dev-mode.json อัปเดตเขตข้อมูลต่อไปนี้เพื่อให้ตรงกับการกําหนดค่าของคุณ:
  - WorkspaceGuid: ID พื้นที่ทํางานของคุณ คุณสามารถค้นหาค่านี้ใน URL ของเบราว์เซอร์เมื่อคุณเลือกพื้นที่ทํางานใน Fabric ตัวอย่างเช่น: https://app.powerbi.com/groups/<WorkspaceID>/
  - ManifestPackageFilePath: ตําแหน่งที่ตั้งของแพคเกจรายชื่อแฟ้ม เมื่อคุณสร้างโซลูชัน จะบันทึกแพคเกจรายชื่อแฟ้มใน src\bin\Debug ข้อมูลเพิ่มเติมเกี่ยวกับแพคเกจรายชื่อแฟ้มมีให้ในภายหลังในบทความ
  - WorkloadEndpointURL: URL จุดสิ้นสุดของปริมาณงาน
3. ใน ไฟล์แพคเกจ/รายชื่อแฟ้ม/WorkloadManifest.xml ให้อัปเดตเขตข้อมูลต่อไปนี้เพื่อให้ตรงกับการกําหนดค่าของคุณ:
  - <AppId>: ID ไคลเอ็นต์ (ID แอปพลิเคชัน) ของแอปพลิเคชันเวิร์กโหลด Microsoft Entra
  - <RedirectUri>: การเปลี่ยนเส้นทาง URI คุณสามารถค้นหาค่านี้ในการลงทะเบียนแอปที่คุณสร้างขึ้นภายใต้ การรับรองความถูกต้องได้
  - <ResourceId>: ผู้ชมสําหรับโทเค็น Microsoft Entra ที่เข้ามา คุณสามารถค้นหาข้อมูลนี้ในการลงทะเบียนแอปที่คุณสร้างขึ้นภายใต้ เปิดเผย API
4. ใน ไฟล์ src/appsettings.json ให้อัปเดตเขตข้อมูลต่อไปนี้เพื่อให้ตรงกับการกําหนดค่าของคุณ:
  - PublisherTenantId: ID ของผู้เช่าของผู้เช่าผู้เผยแพร่ปริมาณงาน
  - ClientId: ID ไคลเอ็นต์ (ID แอปพลิเคชัน) ของแอปพลิเคชัน Microsoft Entra ปริมาณงาน
  - ClientSecret: ข้อมูลลับสําหรับปริมาณงานแอปพลิเคชัน Microsoft Entra
  - ผู้ชม: ผู้ชมสําหรับโทเค็น Microsoft Entra ที่เข้ามา คุณสามารถค้นหาข้อมูลนี้ในการลงทะเบียนแอปที่คุณสร้างขึ้นภายใต้ เปิดเผย API การตั้งค่านี้ยังเรียกว่า URI ของ ID แอปพลิเคชัน
สร้างแพคเกจรายชื่อแฟ้ม

หากต้องการสร้างไฟล์แพคเกจรายชื่อแฟ้ม ให้สร้าง Fabric_Extension_BE_Boilerplate รุ่นเป็นกระบวนการสามขั้นตอนที่สร้างไฟล์แพคเกจรายชื่อแฟ้ม ซึ่งจะเรียกใช้ขั้นตอนเหล่านี้:
1. ทริกเกอร์ ManifestValidator.ps1 บน WorkloadManifest.xml ใน Packages\manifest/ และทริกเกอร์ ItemManifestValidator.ps1 บนรายการทั้งหมด XMLs (ตัวอย่างเช่น Item1.xml) ใน Packages\manifest/ ถ้าการตรวจสอบล้มเหลว ไฟล์ข้อผิดพลาดจะถูกสร้างขึ้น คุณสามารถดูสคริปต์การตรวจสอบใน ValidationScripts/
2. ถ้ามีไฟล์ข้อผิดพลาดอยู่ รุ่นที่ล้มเหลวพร้อมกับข้อผิดพลาดการตรวจสอบความถูกต้องที่มีรายการหรือค่าเริ่มต้น เมื่อต้องการดูไฟล์ข้อผิดพลาดใน Visual Studio ให้ดับเบิลคลิกที่ข้อผิดพลาดในผลลัพธ์การตรวจสอบ
3. หลังจากตรวจสอบสําเร็จ ให้รวมไฟล์ WorkloadManifest.xml และ Item1.xml ลงใน ManifestPackage.1.0.0.nupkg แพคเกจผลลัพธ์อยู่ใน src\bin\Debug
คัดลอกไฟล์ ManifestPackage.1.0.0.nupkg ไปยังเส้นทางที่กําหนดไว้ในไฟล์การกําหนดค่า workload-dev-mode.json
Program.cs คือจุดเข้าใช้งานและสคริปต์การเริ่มต้นสําหรับแอปพลิเคชันของคุณ ในไฟล์นี้ คุณสามารถกําหนดค่าบริการต่าง ๆ เริ่มต้นแอปพลิเคชันและเริ่มโฮสต์เว็บ
สร้างเพื่อให้แน่ใจว่าโครงการของคุณสามารถเข้าถึงการขึ้นต่อกันที่จําเป็นสําหรับการคอมไพล์และการดําเนินการ
ดาวน์โหลด DevGateway จาก ศูนย์ดาวน์โหลดของ Microsoft
เรียกใช้แอปพลิเคชัน Microsoft.Fabric.Workload.DevGateway.exe และลงชื่อเข้าใช้ด้วยผู้ใช้ที่มีสิทธิ์ของผู้ดูแลระบบพื้นที่ทํางานสําหรับพื้นที่ทํางานที่ระบุไว้ในWorkspaceGuidเขตข้อมูลของ workload-dev-mode.json

หลังจากการรับรองความถูกต้อง ปริมาณงานภายนอกจะสร้างการสื่อสารกับ Fabric Backend ผ่าน Azure Relay กระบวนการนี้เกี่ยวข้องกับการลงทะเบียนการถ่ายทอดและการจัดการการสื่อสารที่อํานวยความสะดวกโดยโหนดพร็อกซีที่กําหนด แพคเกจที่ประกอบด้วยรายการปริมาณงานถูกอัปโหลด และเผยแพร่

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

คุณสามารถตรวจสอบข้อผิดพลาดที่อาจเกิดขึ้นในคอนโซล

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

ทํางานกับโครงการตัวอย่างต้นแบบ

การสร้างโค้ด

เราใช้ตัวอย่าง Workload Boilerplate C# ASP.NET Core เพื่อสาธิตวิธีการสร้างปริมาณงานโดยใช้ REST API ตัวอย่างเริ่มต้นด้วยการสร้างเซิร์ฟเวอร์ที่เก็บและคลาสสัญญาตามข้อกําหนดของ Workload API Swagger คุณสามารถสร้างโค้ดโดยใช้เครื่องมือสร้างโค้ด Swagger หลายตัว ตัวอย่างหม้อน้ําใช้ NSwag ตัวอย่างประกอบด้วย สคริปต์บรรทัดคําสั่ง GenerateServerStub.cmd ซึ่งครอบคลุมตัวสร้างรหัส NSwag สคริปต์ใช้พารามิเตอร์เดียวซึ่งเป็นเส้นทางแบบเต็มไปยังไดเรกทอรีการติดตั้ง NSwag นอกจากนี้ยังตรวจสอบไฟล์ข้อกําหนด Swagger (swagger.json) และไฟล์การกําหนดค่า (nswag.json) ในโฟลเดอร์

การดําเนินการสคริปต์นี้จะสร้างไฟล์ C# ที่ชื่อว่า WorkloadAPI_Generated.cs เนื้อหาของไฟล์นี้สามารถแบ่งออกเป็นสามส่วนตามตรรกะตามที่อธิบายไว้ในส่วนถัดไป

ตัวควบคุมต้นขั้ว ASP.NET หลัก

ItemLifecycleController และ JobsController คลาส เป็นการใช้งานที่บางของ ASP.NET ตัวควบคุม Core สําหรับสองชุดย่อยของ API ปริมาณงาน: การจัดการวงจรชีวิตรายการและงาน คลาสเหล่านี้เสียบเข้ากับไปป์ไลน์ ASP.NET Core HTTP ซึ่งทําหน้าที่เป็นจุดรายการสําหรับวิธีการ API ที่กําหนดไว้ในข้อมูลจําเพาะของ Swagger คลาสจะส่งต่อการเรียกใช้ไปยังการดําเนินการ "จริง" ที่ให้ไว้โดยปริมาณงาน

นี่คือตัวอย่างของ CreateItem วิธีการ:

/// <summary>
/// Called by Microsoft Fabric for creating a new item.
/// </summary>
/// <remarks>
/// Upon item creation Fabric performs some basic validations, creates the item with 'provisioning' state and calls this API to notify the workload. The workload is expected to perform required validations, store the item metadata, allocate required resources, and update the Fabric item metadata cache with item relations and ETag. To learn more see [Microsoft Fabric item update flow](https://updateflow).
/// <br/>
/// <br/>This API should accept [SubjectAndApp authentication](https://subjectandappauthentication).
/// <br/>
/// <br/>##Permissions
/// <br/>Permissions are checked by Microsoft Fabric.
/// </remarks>
/// <param name="workspaceId">The workspace ID.</param>
/// <param name="itemType">The item type.</param>
/// <param name="itemId">The item ID.</param>
/// <param name="createItemRequest">The item creation request.</param>
/// <returns>Successfully created.</returns>
[Microsoft.AspNetCore.Mvc.HttpPost, Microsoft.AspNetCore.Mvc.Route("workspaces/{workspaceId}/items/{itemType}/{itemId}")]
public System.Threading.Tasks.Task CreateItem(System.Guid workspaceId, string itemType, System.Guid itemId, [Microsoft.AspNetCore.Mvc.FromBody] CreateItemRequest createItemRequest)
{

 return _implementation.CreateItemAsync(workspaceId, itemType, itemId, createItemRequest);
}

อินเทอร์เฟซสําหรับการใช้งานปริมาณงาน

IItemLifecycleController และ IJobsController เป็นอินเทอร์เฟซสําหรับการใช้งาน "จริง" ที่กล่าวถึงก่อนหน้านี้ พวกเขากําหนดวิธีการเดียวกันซึ่งผู้ควบคุมนําไปใช้

ข้อกําหนดของคลาสสัญญา

คลาสสัญญา C# คือคลาสที่ API ใช้

การใช้งาน

ขั้นตอนถัดไปหลังจากสร้างโค้ดจะใช้IItemLifecycleControllerอินเทอร์เฟซ และIJobsController ในตัวอย่าง ItemLifecycleControllerImpl Boilerplate และใช้ JobsControllerImpl อินเทอร์เฟซเหล่านี้

ตัวอย่างเช่น โค้ดนี้คือการใช้งานของ CreateItem API:

/// <inheritdoc/>
public async Task CreateItemAsync(Guid workspaceId, string itemType, Guid itemId, CreateItemRequest createItemRequest)
{
 var authorizationContext = await _authenticationService.AuthenticateControlPlaneCall(_httpContextAccessor.HttpContext);
 var item = _itemFactory.CreateItem(itemType, authorizationContext);
 await item.Create(workspaceId, itemId, createItemRequest);
}

จัดการส่วนข้อมูลรายการ

วิธีการ API หลายวิธียอมรับ "เพย์โหลด" ประเภทต่าง ๆ เป็นส่วนหนึ่งของเนื้อความคําขอหรือส่งกลับส่วนข้อมูลเป็นส่วนหนึ่งของการตอบสนอง ตัวอย่างเช่น CreateItemRequest มีคุณสมบัติcreationPayload

"CreateItemRequest": {
 "description": "Create item request content.",
 "type": "object",
 "additionalProperties": false,
 "required": [ "displayName" ],
 "properties": {
 "displayName": {
  "description": "The item display name.",
  "type": "string",
  "readOnly": false
 },
 "description": {
  "description": "The item description.",
  "type": "string",
  "readOnly": false
 },
 "creationPayload": {
  "description": "Creation payload specific to the workload and item type, passed by the item editor or as Fabric Automation API parameter.",
  "$ref": "#/definitions/CreateItemPayload",
  "readOnly": false
 }
 }
}

ชนิดสําหรับคุณสมบัติส่วนข้อมูลเหล่านี้จะถูกกําหนดไว้ในข้อมูลจําเพาะของ Swagger มีประเภทเฉพาะสําหรับส่วนข้อมูลทุกประเภท ชนิดเหล่านี้ไม่ได้กําหนดคุณสมบัติเฉพาะใด ๆ และอนุญาตให้รวมคุณสมบัติได้

นี่คือตัวอย่างของ CreateItemPayload ชนิด:

"CreateItemPayload": {
 "description": "Creation payload specific to the workload and item type.",
 "type": "object",
 "additionalProperties": true
}

คลาสสัญญา C# ที่สร้างขึ้นจะถูกกําหนดเป็นpartial แดชบอร์ดและรายงานมีพจนานุกรมที่มีการกําหนดคุณสมบัติไว้

ตัวอย่างมีดังนี้:

/// <summary>
/// Creation payload specific to the workload and item type.
/// </summary>
[System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "13.20.0.0 (NJsonSchema v10.9.0.0 (Newtonsoft.Json v13.0.0.0))")]
public partial class CreateItemPayload
{
 private System.Collections.Generic.IDictionary<string, object> _additionalProperties;

 [Newtonsoft.Json.JsonExtensionData]
 public System.Collections.Generic.IDictionary<string, object> AdditionalProperties
 {
  get { return _additionalProperties ?? (_additionalProperties = new System.Collections.Generic.Dictionary<string, object>()); }
  set { _additionalProperties = value; }
 }
}

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

ตัวอย่างเช่น แฟ้ม CreateItemPayload.cs มีข้อกําหนดเพิ่มเติมสําหรับ CreateItemPayload คลาส

ในตัวอย่างนี้ ข้อกําหนดเพิ่ม Item1Metadata คุณสมบัติ:

namespace Fabric_Extension_BE_Boilerplate.Contracts.FabricAPI.Workload
{
    /// <summary>
    /// Extend the generated class by adding item-type-specific fields.
    /// In this sample every type will have a dedicated property. Alternatively, polymorphic serialization could be used.
    /// </summary>
    public partial class CreateItemPayload
    {
        [Newtonsoft.Json.JsonProperty("item1Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item1Metadata Item1Metadata { get; init; }
    }
}

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

ตัวอย่างเช่น เมื่อต้องการสนับสนุนชนิดหน่วยข้อมูลสองชนิด ข้อกําหนดคลาสต้องถูกขยายเหมือนกับในตัวอย่างต่อไปนี้:

namespace Fabric_Extension_BE_Boilerplate.Contracts.FabricAPI.Workload
{
    public partial class CreateItemPayload
    {
        [Newtonsoft.Json.JsonProperty("item1Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item1Metadata Item1Metadata { get; init; }

        [Newtonsoft.Json.JsonProperty("item2Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item2Metadata Item2Metadata { get; init; }
    } 
}

หมายเหตุ

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

ตัวอย่างเช่น รหัสนี้แสดงให้เห็นว่าการใช้งาน Boilerplate sample item1 จัดการกับส่วนข้อมูลอย่างไร:

protected override void SetDefinition(CreateItemPayload payload)
{
 if (payload == null)
 {
  Logger.LogInformation("No payload is provided for {0}, objectId={1}", ItemType, ItemObjectId);
  _metadata = Item1Metadata.Default.Clone();
  return;
 }

 if (payload.Item1Metadata == null)
 {
  throw new InvalidItemPayloadException(ItemType, ItemObjectId);
 }

 if (payload.Item1Metadata.Lakehouse == null)
 {
  throw new InvalidItemPayloadException(ItemType, ItemObjectId)
   .WithDetail(ErrorCodes.ItemPayload.MissingLakehouseReference, "Missing Lakehouse reference");
 }

 _metadata = payload.Item1Metadata.Clone();
}

แก้ไขปัญหาและดีบัก

ส่วนถัดไปจะอธิบายวิธีการแก้ไขปัญหาและดีบักการปรับใช้ของคุณ

ปัญหาที่ทราบแล้วและวิธีแก้ไข

รับข้อมูลเกี่ยวกับปัญหาที่ทราบแล้วและวิธีแก้ไขปัญหาเหล่านั้น

ไม่มีข้อมูลลับไคลเอ็นต์

ข้อผิดพลาด:

Microsoft.Identity.Client.MsalServiceException: ปัญหาการกําหนดค่าป้องกันการรับรองความถูกต้อง ตรวจสอบข้อความแสดงข้อผิดพลาดจากเซิร์ฟเวอร์สําหรับรายละเอียด คุณสามารถปรับเปลี่ยนการกําหนดค่าในพอร์ทัลการลงทะเบียนแอปพลิเคชัน ดู https://aka.ms/msal-net-invalid-client สําหรับรายละเอียด

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

ความละเอียด: ตรวจสอบให้แน่ใจว่า คุณมีข้อมูลลับของไคลเอ็นต์ที่ถูกต้องที่กําหนดไว้ใน appsettings.json

ข้อผิดพลาด:

Microsoft.Identity.Client.MsalUiRequiredException: AADSTS65001: ผู้ใช้หรือผู้ดูแลระบบไม่ได้รับความยินยอมให้ใช้แอปพลิเคชันที่มี ID <example ID> ส่งคําขอการอนุญาตแบบโต้ตอบสําหรับผู้ใช้และทรัพยากรนี้

การแก้ไขปัญหา:

ในตัวแก้ไขรายการ ไปที่ด้านล่างสุดของความเจ็บปวด และเลือก นําทางไปยังหน้าการรับรองความถูกต้อง
ภายใต้ ขอบเขต ใส่ .default แล้วเลือก รับโทเค็นการเข้าถึง
ในกล่องโต้ตอบ ให้อนุมัติการปรับปรุง

การสร้างรายการล้มเหลวเนื่องจากการเลือกความจุ

ข้อผิดพลาด:

PriorityPlacement: ไม่มีบริการหลักที่พร้อมใช้งานสําหรับการวางลําดับความสําคัญ เฉพาะ name, guidและ workload-name จะพร้อมใช้งาน

การแก้ไขปัญหา:

ในฐานะผู้ใช้ คุณอาจสามารถเข้าถึงได้เฉพาะความจุรุ่นทดลองใช้เท่านั้น ตรวจสอบให้แน่ใจว่าคุณใช้ความจุที่คุณสามารถเข้าถึงได้

ความล้มเหลวในการสร้างไฟล์ด้วยข้อผิดพลาด 404 (NotFound)

ข้อผิดพลาด:

การสร้างไฟล์ใหม่ล้มเหลวสําหรับ filePath: 'workspace-id'/'lakehouse-id'/Files/data.json รหัสสถานะการตอบกลับไม่ได้ระบุความสําเร็จ: 404 (NotFound)

การแก้ไขปัญหา:

ตรวจสอบให้แน่ใจว่า คุณกําลังทํางานกับ URL ของ OneLake DFS ที่เหมาะกับสภาพแวดล้อมของคุณ ตัวอย่างเช่น หากคุณทํางานกับสภาพแวดล้อม PPE ให้เปลี่ยน EnvironmentConstants.OneLakeDFSBaseUrlConstants.cs เป็น URL ที่เหมาะสม

แก้จุดบกพร่อง

เมื่อคุณแก้ไขปัญหาการดําเนินงานต่างๆ คุณสามารถตั้งค่าจุดสั่งหยุดในรหัสเพื่อวิเคราะห์และแก้ไขจุดบกพร่องลักษณะการทํางานได้ ทําตามขั้นตอนเหล่านี้สําหรับการดีบักที่มีประสิทธิภาพ:

เปิดรหัสในสภาพแวดล้อมการพัฒนาของคุณ
ไปที่ฟังก์ชันตัวจัดการการดําเนินการที่เกี่ยวข้อง (ตัวอย่างเช่น OnCreateFabricItemAsync สําหรับการดําเนินการ CRUD หรือจุดสิ้นสุดในตัวควบคุมสําหรับ execute การดําเนินการ)
วางจุดสั่งหยุดที่บรรทัดเฉพาะที่คุณต้องการตรวจสอบรหัส
รันแอพลิเคชันในโหมดดีบัก
ทริกเกอร์การดําเนินการจาก frontend ที่คุณต้องการแก้จุดบกพร่อง

ตัวดีบักหยุดการดําเนินการที่จุดสั่งหยุดที่ระบุเพื่อให้คุณสามารถตรวจสอบตัวแปร ก้าวผ่านรหัส และระบุปัญหาได้

สกรีนช็อตของโปรแกรมตัวอย่างที่มีจุดสั่งหยุดสําหรับการดีบัก

พื้นที่ทำงาน

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

สกรีนช็อตของ UI สําหรับการตั้งชื่อรายการปริมาณงานตัวอย่าง

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

สนับสนุน

เรายินดีสนับสนุนโครงการนี้ หากคุณพบปัญหาใด ๆ หรือต้องการเพิ่มคุณลักษณะใหม่ ให้ทําตามขั้นตอนเหล่านี้:

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

แชร์ผ่าน

ใช้ Backend ของ Microsoft Fabric

Frontend

Backend

Azure Relay และ DevGateway

การรวมเลคเฮ้าส์

การรับรองความถูกต้องและการรักษาความปลอดภัย

ข้อกำหนดเบื้องต้น

การจัดการแพคเกจ NuGet

การขึ้นต่อกัน

เริ่มต้นใช้งาน

ทํางานกับโครงการตัวอย่างต้นแบบ

การสร้างโค้ด

ตัวควบคุมต้นขั้ว ASP.NET หลัก

อินเทอร์เฟซสําหรับการใช้งานปริมาณงาน

ข้อกําหนดของคลาสสัญญา

การใช้งาน

จัดการส่วนข้อมูลรายการ

แก้ไขปัญหาและดีบัก

ปัญหาที่ทราบแล้วและวิธีแก้ไข

ไม่มีข้อมูลลับไคลเอ็นต์

การสร้างรายการล้มเหลวเนื่องจากการเลือกความจุ

ความล้มเหลวในการสร้างไฟล์ด้วยข้อผิดพลาด 404 (NotFound)

แก้จุดบกพร่อง

พื้นที่ทำงาน

สนับสนุน

คำติชม

แหล่งทรัพยากรเพิ่มเติม

แชร์ผ่าน

ใช้ Backend ของ Microsoft Fabric

Frontend

Backend

Azure Relay และ DevGateway

การรวมเลคเฮ้าส์

การรับรองความถูกต้องและการรักษาความปลอดภัย

ข้อกำหนดเบื้องต้น

การจัดการแพคเกจ NuGet

การขึ้นต่อกัน

เริ่มต้นใช้งาน

ทํางานกับโครงการตัวอย่างต้นแบบ

การสร้างโค้ด

ตัวควบคุมต้นขั้ว ASP.NET หลัก

อินเทอร์เฟซสําหรับการใช้งานปริมาณงาน

ข้อกําหนดของคลาสสัญญา

การใช้งาน

จัดการส่วนข้อมูลรายการ

แก้ไขปัญหาและดีบัก

ปัญหาที่ทราบแล้วและวิธีแก้ไข

ไม่มีข้อมูลลับไคลเอ็นต์

ข้อผิดพลาดในระหว่างการสร้างรายการเนื่องจากการยินยอมของผู้ดูแลระบบหายไป

การสร้างรายการล้มเหลวเนื่องจากการเลือกความจุ

ความล้มเหลวในการสร้างไฟล์ด้วยข้อผิดพลาด 404 (NotFound)

แก้จุดบกพร่อง

พื้นที่ทำงาน

สนับสนุน

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

คำติชม

แหล่งทรัพยากรเพิ่มเติม