Κοινή χρήση μέσω

Υλοποίηση του παρασκηνίου Microsoft Fabric

  • Άρθρο

Αυτό το δείγμα αποθετηρίου δεδομένων ανάπτυξης φόρτου εργασίας Microsoft Fabric είναι ένα σημείο εκκίνησης για τη δημιουργία εφαρμογών που απαιτούν ενοποίηση με διάφορες υπηρεσίες και για ενοποίηση με την αρχιτεκτονική lakehouse. Αυτό το άρθρο σάς βοηθά να ρυθμίσετε το περιβάλλον και να ρυθμίσετε τις παραμέτρους των απαραίτητων στοιχείων για να ξεκινήσετε. Το άρθρο περιγράφει βασικά στοιχεία και τους ρόλους τους στην αρχιτεκτονική.

Προσκηνίου

Το προσκήνιο είναι το σημείο όπου διαχειρίζεστε την εμπειρία χρήστη (UX) και τη συμπεριφορά. Επικοινωνεί με την πύλη προσκηνίου Fabric μέσω ενός iFrame για τη διευκόλυνση της απρόσκοπτης αλληλεπίδρασης.

Για περισσότερες πληροφορίες, ανατρέξτε στο προσκήνιο για το Κιτ ανάπτυξης φόρτου εργασίας Microsoft Fabric.

Παρασκήνιο

Το παρασκήνιο αποθηκεύει δεδομένα και μετα-δεδομένα. Χρησιμοποιεί τις λειτουργίες Δημιουργία, Ανάγνωση, Ενημέρωση και Διαγραφή (CRUD) για τη δημιουργία στοιχείων φόρτου εργασίας και μετα-δεδομένων και εκτελεί εργασίες για τη συμπλήρωση δεδομένων στον χώρο αποθήκευσης. Η επικοινωνία μεταξύ προσκηνίου και παρασκηνίου πραγματοποιείται μέσω δημόσιων API.

Αναμετάδοση Azure και DevGateway

Η αναμετάδοση Azure επιτρέπει την επικοινωνία μεταξύ του τοπικού περιβάλλοντος ανάπτυξης και του παρασκηνίου Fabric σε λειτουργία προγραμματιστή. Σε λειτουργία προγραμματιστή, ο φόρτος εργασίας λειτουργεί στον υπολογιστή του προγραμματιστή.

Το βοηθητικό πρόγραμμα DevGateway έχει δύο ρόλους:

  • Χειρίζεται την πλευρά του φόρτου εργασίας στο κανάλι αναμετάδοσης Azure και διαχειρίζεται την καταχώρηση της τοπικής παρουσίας φόρτου εργασίας με το Fabric στο περιβάλλον συγκεκριμένου συνόλου εκχωρημένων πόρων. Το DevGateway καθιστά τον φόρτο εργασίας προσβάσιμο σε όλους τους χώρους εργασίας που έχουν ανατεθεί σε αυτό το σύνολο εκχωρημένων πόρων. Το βοηθητικό πρόγραμμα χειρίζεται την κατάργηση της συνάθροισης όταν διακόπτεται το κανάλι.
  • Λειτουργεί με κλήσεις API φόρτου εργασίας azure αναμετάδοσης στο κανάλι από το Fabric στον φόρτο εργασίας.

Οι κλήσεις API ελέγχου φόρτου εργασίας γίνονται απευθείας από τον φόρτο εργασίας στο Fabric. Το κανάλι αναμετάδοσης Azure δεν απαιτείται για τις κλήσεις.

Ενοποίηση Lakehouse

Η αρχιτεκτονική του κιτ ανάπτυξης φόρτου εργασίας ενοποιείται απρόσκοπτα με μια αρχιτεκτονική lakehouse για λειτουργίες όπως η αποθήκευση, η ανάγνωση και η λήψη δεδομένων. Η αλληλεπίδραση διευκολύνεται μέσω της αναμετάδοσης Azure και του SDK Fabric για την εξασφάλιση ασφαλούς επικοινωνίας και ελέγχου ταυτότητας. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Εργασία με δεδομένα πελατών.

Έλεγχος ταυτότητας και ασφάλεια

Το Microsoft Entra ID χρησιμοποιείται για ασφαλή έλεγχο ταυτότητας, εξασφαλίζοντας ότι όλες οι αλληλεπιδράσεις εντός της αρχιτεκτονικής είναι εξουσιοδοτημένες και ασφαλείς.

Η επισκόπηση του κιτ ανάπτυξης παρέχει μια ματιά στην αρχιτεκτονική μας. Για περισσότερες πληροφορίες σχετικά με τον τρόπο ρύθμισης των παραμέτρων των έργων, για οδηγίες ελέγχου ταυτότητας και για να ξεκινήσετε, ανατρέξτε στα παρακάτω άρθρα:

Διάγραμμα που δείχνει πώς το Fabric SDK ενοποιείται με το Fabric.

Το προσκήνιο δημιουργεί επικοινωνία με την πύλη προσκηνίου Fabric μέσω ενός iFrame. Η πύλη με τη σειρά της αλληλεπιδρά με το παρασκήνιο Fabric πραγματοποιώντας κλήσεις στα εκτεθειμένα δημόσια API.

Για αλληλεπιδράσεις μεταξύ του πλαισίου ανάπτυξης παρασκηνίου και του παρασκηνίου Fabric, η αναμετάδοση Azure χρησιμεύει ως αγωγός. Επιπλέον, το πλαίσιο ανάπτυξης παρασκηνίου ενοποιείται απρόσκοπτα με το Lakehouse. Η επικοινωνία διευκολύνεται με τη χρήση της αναμετάδοσης Azure και του Κιτ ανάπτυξης λογισμικού Fabric (SDK) που είναι εγκατεστημένο στο πλαίσιο ανάπτυξης παρασκηνίου.

Ο έλεγχος ταυτότητας για όλες τις επικοινωνίες σε αυτά τα στοιχεία εξασφαλίζεται μέσω του Microsoft Entra. Το Microsoft Entra παρέχει ένα ασφαλές και πιστοποιημένο περιβάλλον για τις αλληλεπιδράσεις μεταξύ προσκηνίου, παρασκηνίου, Αναμετάδοσης Azure, Fabric SDK και Lakehouse.

Προαπαιτούμενα στοιχεία

Βεβαιωθείτε ότι η Διαχείριση πακέτων NuGet είναι ενσωματωμένη στην εγκατάσταση του Visual Studio. Αυτό το εργαλείο απαιτείται για την απλοποιημένη διαχείριση εξωτερικών βιβλιοθηκών και πακέτων που είναι απαραίτητα για το έργο μας.

Διαχείριση πακέτων NuGet

  • <NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile> και <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>: Αυτές οι ιδιότητες καθορίζουν τη διαδρομή προς τα αρχεία NuSpec που χρησιμοποιούνται για τη δημιουργία του πακέτου NuGet για τις λειτουργίες εντοπισμού σφαλμάτων και έκδοσης. Το αρχείο NuSpec περιέχει μετα-δεδομένα σχετικά με το πακέτο, όπως το αναγνωριστικό, την έκδοση, τις εξαρτήσεις του και άλλες σχετικές πληροφορίες.

  • <GeneratePackageOnBuild>true</GeneratePackageOnBuild>: Όταν οριστεί σε true, αυτή η ιδιότητα καθοδηγεί τη διαδικασία δόμησης ώστε να δημιουργεί αυτόματα ένα πακέτο NuGet κατά τη διάρκεια κάθε δόμησης. Αυτή η ιδιότητα είναι χρήσιμη για να εξασφαλίσετε ότι το πακέτο είναι πάντα ενημερωμένο με τις τελευταίες αλλαγές στο έργο.

  • <IsPackable>true</IsPackable>: Όταν οριστεί σε true, αυτή η ιδιότητα υποδεικνύει ότι το έργο μπορεί να συσκευαστεί σε ένα πακέτο NuGet. Η δυνατότητα συσκευασίας είναι μια βασική ιδιότητα για έργα που προορίζονται για την παραγωγή πακέτων NuGet κατά τη διαδικασία δόμησης.

Το πακέτο NuGet που δημιουργήθηκε για τη λειτουργία εντοπισμού σφαλμάτων βρίσκεται στον κατάλογο src\bin\Debug μετά τη διαδικασία δόμησης.

Όταν εργάζεστε σε λειτουργία cloud, μπορείτε να αλλάξετε τη ρύθμιση παραμέτρων δόμησης του Visual Studio σε Έκδοση και να δημιουργήσετε το πακέτο σας. Το πακέτο που δημιουργήθηκε βρίσκεται στον src\bin\Release κατάλογο. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Οδηγός εργασίας σε λειτουργία cloud.

Εξαρτήσεις

  • Το δείγμα boilerplate παρασκηνίου εξαρτάται από τα παρακάτω πακέτα Azure SDK:

    • Azure.Core
    • Azure.Identity
    • Azure.Storage.Files.DataLake
    • Το πακέτο Microsoft Identity

Για να ρυθμίσετε τις παραμέτρους του NuGet Package Manager, καθορίστε τη διαδρομή στην ενότητα Προελεύσεις πακέτου προτού ξεκινήσετε τη διαδικασία δόμησης.

<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>

Έναρξη

Για να ρυθμίσετε το δείγμα έργου φόρτου εργασίας στον τοπικό υπολογιστή σας:

  1. Κλωνοποιήστε το αποθετήριο: Εκτελέστε git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample.git.

  2. Στο Visual Studio 2022, ανοίξτε τη λύση.

  3. Ρυθμίστε μια καταχώρηση εφαρμογής ακολουθώντας τις οδηγίες στο εκπαιδευτικό βοήθημα ελέγχου ταυτότητας. Βεβαιωθείτε ότι τα έργα προσκηνίου και παρασκηνίου έχουν τις απαραίτητες ρυθμίσεις που περιγράφονται στο άρθρο. Το Microsoft Entra χρησιμοποιείται για ασφαλή έλεγχο ταυτότητας, ώστε να εξασφαλίζεται ότι όλες οι αλληλεπιδράσεις εντός της αρχιτεκτονικής είναι εξουσιοδοτημένες και ασφαλείς.

  4. Ενημερώστε τη διεύθυνση URL βάσης Microsoft OneLake DFS. Ανάλογα με το περιβάλλον Fabric, ίσως μπορείτε να ενημερώσετε την τιμή για OneLakeDFSBaseURL το στο φάκελο src\Constants . Η προεπιλογή είναι onelake.dfs.fabric.microsoft.com, αλλά μπορείτε να ενημερώσετε τη διεύθυνση URL ώστε να αντικατοπτρίζει το περιβάλλον σας. Για περισσότερες πληροφορίες σχετικά με τις διαδρομές DFS, ανατρέξτε στην τεκμηρίωση του OneLake.

  5. Ρυθμίστε τη ρύθμιση παραμέτρων φόρτου εργασίας.

    1. Αντιγράψτε workload-dev-mode.json από το src/Config στη C:.
    2. Στο αρχείο workload-dev-mode.json, ενημερώστε τα παρακάτω πεδία ώστε να συμφωνούν με τις ρυθμίσεις παραμέτρων σας:
      • WorkspaceGuid: Το αναγνωριστικό του χώρου εργασίας σας. Μπορείτε να βρείτε αυτή την τιμή στη διεύθυνση URL του προγράμματος περιήγησης όταν επιλέγετε έναν χώρο εργασίας στο Fabric. Για παράδειγμα, https://app.powerbi.com/groups/<WorkspaceID>/.
      • ManifestPackageFilePath: Η θέση του πακέτου διακήρυξης. Όταν δημιουργείτε τη λύση, αποθηκεύει το πακέτο διακήρυξης στο src\bin\Debug. Περισσότερες πληροφορίες σχετικά με το πακέτο διακήρυξης παρέχονται αργότερα στο άρθρο.
      • Φόρτος εργασίαςEndpointURL: Η διεύθυνση URL τελικού σημείου φόρτου εργασίας.
    3. Στο αρχείο Πακέτα/διακήρυξη/WorkloadManifest.xml, ενημερώστε τα παρακάτω πεδία ώστε να συμφωνούν με τις ρυθμίσεις παραμέτρων σας:
      • <AppId>: Το αναγνωριστικό προγράμματος-πελάτη (Αναγνωριστικό εφαρμογής) του φόρτου εργασίας της εφαρμογής Microsoft Entra.
      • <RedirectUri>: Τα URIs ανακατεύθυνσης. Μπορείτε να βρείτε αυτή την τιμή στην καταχώρηση εφαρμογής που δημιουργήσατε, στην περιοχή Έλεγχος ταυτότητας.
      • <ResourceId>: Το κοινό για τα εισερχόμενα διακριτικά Του Microsoft Entra. Μπορείτε να βρείτε αυτές τις πληροφορίες στην καταχώρηση εφαρμογής που δημιουργήσατε, στην περιοχή Έκθεση API.
    4. Στο αρχείο src/appsettings.json, ενημερώστε τα παρακάτω πεδία ώστε να συμφωνούν με τις ρυθμίσεις παραμέτρων σας:
      • PublisherTenantId: Το αναγνωριστικό του μισθωτή εκδότη φόρτου εργασίας.
      • ClientId: Το αναγνωριστικό προγράμματος-πελάτη (αναγνωριστικό εφαρμογής) του φόρτου εργασίας της εφαρμογής Microsoft Entra.
      • ClientSecret: Ο μυστικός κωδικός για την εφαρμογή Microsoft Entra φόρτου εργασίας.
      • Ακροατήριο: Το ακροατήριο για τα εισερχόμενα διακριτικά Microsoft Entra. Μπορείτε να βρείτε αυτές τις πληροφορίες στην καταχώρηση εφαρμογής που δημιουργήσατε, στην περιοχή Έκθεση API. Αυτή η ρύθμιση ονομάζεται επίσης αναγνωριστικό εφαρμογής URI.

  6. Δημιουργήστε ένα πακέτο διακήρυξης.

    Για να δημιουργήσετε ένα αρχείο πακέτου διακήρυξης, δημιουργήστε 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 .

  7. Program.cs είναι η δέσμη ενεργειών σημείου εισόδου και εκκίνησης για την εφαρμογή σας. Σε αυτό το αρχείο, μπορείτε να ρυθμίσετε τις παραμέτρους διάφορων υπηρεσιών, να προετοιμάσετε την εφαρμογή και να εκκινήσετε τον κεντρικό υπολογιστή Web.

  8. Δόμηση για να εξασφαλίσετε ότι το έργο σας έχει πρόσβαση στις απαιτούμενες εξαρτήσεις για μεταγλώττιση και εκτέλεση.

  9. Λήψη του DevGateway από το Κέντρο λήψης αρχείων της Microsoft

  10. Εκτελέστε την εφαρμογή Microsoft.Fabric.Workload.DevGateway.exe και πραγματοποιήστε είσοδο με έναν χρήστη που διαθέτει δικαιώματα διαχειριστή χώρου εργασίας για τον χώρο εργασίας που καθορίζεται στο WorkspaceGuid πεδίο του workload-dev-mode.json.

    Στιγμιότυπο οθόνης της σελίδας εισόδου της Microsoft.

    Μετά τον έλεγχο ταυτότητας, οι εξωτερικοί φόρτοι εργασίας δημιουργούν επικοινωνία με το παρασκήνιο Fabric μέσω της αναμετάδοσης Azure. Αυτή η διαδικασία περιλαμβάνει την αναμετάδοση της εγγραφής και της διαχείρισης επικοινωνιών που διευκολύνεται από έναν καθορισμένο κόμβο διακομιστή μεσολάβησης. Το πακέτο που περιέχει τη διακήρυξη φόρτου εργασίας αποστέλλεται και δημοσιεύεται.

    Σε αυτό το στάδιο, το Fabric εντοπίζει τον φόρτο εργασίας και ενσωματώνει τους εκχωρημένους πόρους του.

    Μπορείτε να παρακολουθείτε για πιθανά σφάλματα στην κονσόλα.

    Εάν δεν εμφανίζονται σφάλματα, πραγματοποιείται η σύνδεση, εκτελείται με επιτυχία η εγγραφή και η διακήρυξη φόρτου εργασίας αποστέλλεται συστηματικά.

    Στιγμιότυπο οθόνης της φόρτωσης σύνδεσης χωρίς σφάλματα.

  11. Στο Visual Studio, αλλάξτε το έργο εκκίνησης σε έργο Boilerplate και επιλέξτε Εκτέλεση.

    Στιγμιότυπο οθόνης του περιβάλλοντος εργασίας χρήστη για έργο εκκίνησης στο Visual Studio.

Εργασία με το δείγμα έργου Boilerplate

Δημιουργία κώδικα

Χρησιμοποιούμε το δείγμα Boilerplate C# ASP.NET Core φόρτου εργασίας για να δείξουμε πώς μπορείτε να δημιουργήσετε έναν φόρτο εργασίας χρησιμοποιώντας API REST. Το δείγμα ξεκινά με τη δημιουργία στελεχών διακομιστή και κλάσεων σύμβασης με βάση την προδιαγραφή API Swagger φόρτου εργασίας. Μπορείτε να δημιουργήσετε τον κώδικα χρησιμοποιώντας οποιοδήποτε από τα διάφορα εργαλεία δημιουργίας κώδικα Swagger. Το δείγμα boilerplate χρησιμοποιεί NSwag. Το δείγμα περιέχει τη δέσμη ενεργειών γραμμής εντολών GenerateServerStub.cmd , η οποία ενσωματώνει τη δημιουργία κώδικα NSwag. Η δέσμη ενεργειών λαμβάνει μια μοναδική παράμετρο, η οποία είναι μια πλήρης διαδρομή προς τον κατάλογο εγκατάστασης NSwag. Ελέγχει επίσης για το αρχείο ορισμού Swagger (swagger.json) και το αρχείο ρύθμισης παραμέτρων (nswag.json) στον φάκελο.

Η εκτέλεση αυτής της δέσμης ενεργειών παράγει ένα αρχείο C# με την ονομασία WorkloadAPI_Generated.cs. Τα περιεχόμενα αυτού του αρχείου μπορούν λογικά να διαιρεθούν σε τρία μέρη, όπως εξηγείται στις επόμενες ενότητες.

ελεγκτές αποκομμάτων ASP.NET πυρήνων

ItemLifecycleController Οι και JobsController οι είναι μικρές υλοποιήσεις του ASP.NET Core controllers για δύο υποσύνολα του API φόρτου εργασίας: διαχείριση κύκλου ζωής στοιχείων και εργασίες. Αυτές οι συνδέονται στη διοχέτευση HTTP ASP.NET Core. Χρησιμεύουν ως σημεία εισόδου για τις μεθόδους 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 . Στο δείγμα Boilerplate και ItemLifecycleControllerImpl JobsControllerImpl υλοποιήστε αυτές τις διασυνδέσεις.

Για παράδειγμα, αυτός ο κώδικας είναι η υλοποίηση του API CreateItem:

/// <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 κλάση πρέπει να μπορεί να χειριστεί διαφορετικούς τύπους ωφέλιμου φορτίου δημιουργίας με ένα τύπο ανά στοιχείο. Έχετε δύο επιλογές. Ο απλούστερος τρόπος, που χρησιμοποιείται στο δείγμα Boilerplate, είναι να ορίσετε πολλές προαιρετικές ιδιότητες, καθεμία από τις οποίες αντιπροσωπεύει το ωφέλιμο φορτίο δημιουργίας για έναν διαφορετικό τύπο στοιχείου. Κάθε αίτηση έπειτα έχει μόνο ένα από αυτά τα σύνολα ιδιοτήτων, σύμφωνα με τον τύπο στοιχείου που δημιουργείται. Εναλλακτικά, μπορείτε να εφαρμόσετε πολυμορφική σειριοποίηση, αλλά αυτή η επιλογή δεν φαίνεται στο δείγμα επειδή η επιλογή δεν παρέχει σημαντικά οφέλη.

Για παράδειγμα, για την υποστήριξη δύο τύπων στοιχείων, ο ορισμός κλάσης πρέπει να επεκταθεί όπως στο παρακάτω παράδειγμα:

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 ή το REST API Αυτοματισμού Fabric. Το πρόγραμμα-πελάτης είναι υπεύθυνο για την αποστολή του σωστού ωφέλιμου φορτίου και την αντιστοίχιση του τύπου του στοιχείου. Ο φόρτος εργασίας είναι υπεύθυνος για την επαλήθευση. Το Fabric αντιμετωπίζει αυτό το ωφέλιμο φορτίο ως αδιαφανές αντικείμενο και το μεταφέρει μόνο από το πρόγραμμα-πελάτη στον φόρτο εργασίας. Παρομοίως, για ένα ωφέλιμο φορτίο που επιστρέφεται από τον φόρτο εργασίας στον υπολογιστή-πελάτη, είναι ευθύνη του φόρτου εργασίας και του προγράμματος-πελάτη να χειρίζεται σωστά το ωφέλιμο φορτίο.

Για παράδειγμα, αυτός ο κώδικας εμφανίζει τον τρόπο με τον οποίο το δείγμα υλοποίησης Boilerplate 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: Παρέχεται μη έγκυρος μυστικός κωδικός προγράμματος-πελάτη. Βεβαιωθείτε ότι ο μυστικός κωδικός που αποστέλλεται στην αίτηση είναι η τιμή του μυστικού κωδικού προγράμματος-πελάτη και όχι το μυστικό αναγνωριστικό προγράμματος-πελάτη για έναν μυστικό κωδικό που προστίθεται στη ρύθμιση της εφαρμογής app_guid .

Επίλυση: Βεβαιωθείτε ότι έχετε ορίσει τον σωστό μυστικό κωδικό προγράμματος-πελάτη σε appsettings.json.

Σφάλμα:

Microsoft.Identity.Client.MsalUiRequiredException: AADSTS65001: Ο χρήστης ή ο διαχειριστής δεν συναινούν στη χρήση της εφαρμογής με αναγνωριστικό <example ID>. Στείλτε μια αλληλεπιδραστική αίτηση εξουσιοδότησης για αυτόν τον χρήστη και τον πόρο.

Επίλυση:

  1. Στο πρόγραμμα επεξεργασίας στοιχείων, μεταβείτε στο κάτω μέρος του πόνου και επιλέξτε Μετάβαση στη σελίδα ελέγχου ταυτότητας.

  2. Στην περιοχή Εμβέλειες, πληκτρολογήστε .default και, στη συνέχεια, επιλέξτε Λήψη διακριτικού πρόσβασης.

  3. Στο παράθυρο διαλόγου, εγκρίνετε την αναθεώρηση.

Η δημιουργία στοιχείου αποτυγχάνει λόγω της επιλογής εκχωρημένων πόρων

Σφάλμα:

PriorityPlacement: Δεν υπάρχουν διαθέσιμες βασικές υπηρεσίες για τοποθέτηση προτεραιότητας. Μόνο nameτα , guidκαι workload-name είναι διαθέσιμα.

Επίλυση:

Ως χρήστης, μπορεί να έχετε πρόσβαση μόνο σε εκχωρημένους πόρους δοκιμαστικής έκδοσης. Βεβαιωθείτε ότι χρησιμοποιείτε εκχωρημένους πόρους στους οποίους έχετε πρόσβαση.

Αποτυχία δημιουργίας αρχείου με σφάλμα 404 (NotFound)

Σφάλμα:

Η δημιουργία ενός νέου αρχείου απέτυχε για το filePath: 'workspace-id'/'lakehouse-id'/Files/data.json. Ο κωδικός κατάστασης απόκρισης δεν υποδεικνύει επιτυχία: 404 (NotFound).

Επίλυση:

Βεβαιωθείτε ότι εργάζεστε με τη διεύθυνση URL OneLake DFS που ταιριάζει στο περιβάλλον σας. Για παράδειγμα, εάν εργάζεστε με ένα περιβάλλον PPE, αλλάξτε EnvironmentConstants.OneLakeDFSBaseUrl Constants.cs στην κατάλληλη διεύθυνση URL.

Εντοπισμός σφαλμάτων

Όταν αντιμετωπίζετε προβλήματα σε διάφορες λειτουργίες, μπορείτε να ορίσετε σημεία διακοπής στον κώδικα για ανάλυση και εντοπισμό σφαλμάτων της συμπεριφοράς. Ακολουθήστε τα παρακάτω βήματα για αποτελεσματικό εντοπισμό σφαλμάτων:

  1. Ανοίξτε τον κώδικα στο περιβάλλον ανάπτυξης.
  2. Μεταβείτε στη σχετική συνάρτηση χειρισμού λειτουργίας (για παράδειγμα, OnCreateFabricItemAsync για λειτουργίες CRUD ή ένα τελικό σημείο σε έναν ελεγκτή για execute λειτουργίες).
  3. Τοποθετήστε σημεία διακοπής σε συγκεκριμένες γραμμές όπου θέλετε να ελέγξετε τον κώδικα.
  4. Εκτελέστε την εφαρμογή σε λειτουργία εντοπισμού σφαλμάτων.
  5. Ενεργοποιήστε τη λειτουργία από το προσκήνιο για τον εντοπισμό σφαλμάτων.

Το πρόγραμμα εντοπισμού σφαλμάτων διακόπτει την εκτέλεση στα καθορισμένα σημεία διακοπής, ώστε να μπορείτε να εξετάσετε μεταβλητές, να περάσετε από τον κώδικα και να εντοπίσετε προβλήματα.

Στιγμιότυπο οθόνης δείγματος προγράμματος με σημεία διακοπής για εντοπισμό σφαλμάτων.

Χώρος εργασίας

Εάν συνδέετε ένα παρασκήνιο στο δείγμα έργου φόρτου εργασίας, το στοιχείο σας πρέπει να ανήκει σε έναν χώρο εργασίας που σχετίζεται με εκχωρημένους πόρους. Από προεπιλογή, ο χώρος εργασίας μου δεν είναι συσχετισμένος με εκχωρημένους πόρους. Διαφορετικά, μπορεί να λάβετε το σφάλμα που εμφανίζεται στο παρακάτω στιγμιότυπο οθόνης:

Στιγμιότυπο οθόνης του περιβάλλοντος εργασίας χρήστη για την ονομασία ενός δείγματος στοιχείου φόρτου εργασίας.

  1. Μεταβείτε σε έναν επώνυμο χώρο εργασίας. Αφήστε το προεπιλεγμένο όνομα χώρου εργασίας Ο χώρος εργασίας μου.

    Στιγμιότυπο οθόνης του περιβάλλοντος εργασίας χρήστη για τη δημιουργία δείγματος φόρτου εργασίας.

  2. Από τον σωστό χώρο εργασίας, φορτώστε το δείγμα φόρτου εργασίας και συνεχίστε με τις δοκιμές:

    Στιγμιότυπο οθόνης του περιβάλλοντος εργασίας χρήστη για τη δημιουργία δείγματος στοιχείου φόρτου εργασίας.

Συνεισφορά

Είναι ευπρόσδεκτες οι συνεισφορές σε αυτό το έργο. Εάν εντοπίσετε προβλήματα ή θέλετε να προσθέσετε νέες δυνατότητες, ακολουθήστε τα εξής βήματα:

  1. Διακλαδώσετε το αποθετήριο.
  2. Δημιουργήστε έναν νέο κλάδο για τη δυνατότητα ή την επιδιόρθωση σφαλμάτων.
  3. Κάντε τις αλλαγές σας και, στη συνέχεια, δεσμεύστε τις.
  4. Προωθήστε τις αλλαγές σας στο διακλαδωμένο αποθετήριο δεδομένων σας.
  5. Δημιουργήστε ένα αίτημα έλξης που έχει μια σαφή περιγραφή των αλλαγών σας.

Σχετικό περιεχόμενο