Implementowanie zaplecza usługi Microsoft Fabric

Artykuł
11/24/2024

To przykładowe repozytorium tworzenia obciążeń usługi Microsoft Fabric to punkt wyjścia do tworzenia aplikacji wymagających integracji z różnymi usługami i integracji z architekturą typu lakehouse. Ten artykuł ułatwia skonfigurowanie środowiska i skonfigurowanie niezbędnych składników do rozpoczęcia pracy. W tym artykule opisano kluczowe składniki i ich role w architekturze.

Fronton

Fronton to miejsce, w którym zarządzasz środowiskiem użytkownika (UX) i zachowaniem. Komunikuje się z portalem frontonu sieci szkieletowej za pośrednictwem elementu iFrame, aby ułatwić bezproblemową interakcję.

Aby uzyskać więcej informacji, zobacz fronton zestawu Microsoft Fabric Workload Development Kit.

Zaplecze

Zaplecze przechowuje zarówno dane, jak i metadane. Używa operacji tworzenia, odczytu, aktualizacji i usuwania (CRUD) w celu utworzenia elementów i metadanych obciążenia oraz wykonywania zadań w celu wypełnienia danych w magazynie. Komunikacja między frontonem a zapleczem jest ustanawiana za pośrednictwem publicznych interfejsów API.

Azure Relay i DevGateway

Usługa Azure Relay umożliwia komunikację między lokalnym środowiskiem projektowym a zapleczem sieci szkieletowej w trybie dewelopera. W trybie dewelopera obciążenie działa na maszynie dewelopera.

Narzędzie DevGateway ma dwie role:

Obsługuje on stronę obciążenia kanału usługi Azure Relay i zarządza rejestracją lokalnego wystąpienia obciążenia za pomocą usługi Fabric w kontekście określonej pojemności. Usługa DevGateway udostępnia obciążenie we wszystkich obszarach roboczych przypisanych do tej pojemności. Narzędzie obsługuje wyrejestrowanie po zatrzymaniu kanału.
Współdziała ona z usługą Azure Relay w celu kanału wywołań interfejsu API obciążenia z sieci szkieletowej do obciążenia.

Wywołania interfejsu API kontroli obciążenia są wykonywane bezpośrednio z obciążenia do sieci szkieletowej. Kanał usługi Azure Relay nie jest wymagany dla wywołań.

Integracja usługi Lakehouse

Architektura zestawu deweloperów obciążeń bezproblemowo integruje się z architekturą typu lakehouse na potrzeby operacji, takich jak zapisywanie, odczytywanie i pobieranie danych. Interakcja jest ułatwiana za pośrednictwem usługi Azure Relay i zestawu SDK sieci szkieletowej w celu zapewnienia bezpiecznej i uwierzytelnionej komunikacji. Aby uzyskać więcej informacji, zobacz Praca z danymi klientów.

Uwierzytelnianie i zabezpieczenia

Identyfikator Entra firmy Microsoft jest używany do bezpiecznego uwierzytelniania, zapewniając, że wszystkie interakcje w architekturze są autoryzowane i bezpieczne.

Omówienie zestawu deweloperów zawiera wgląd w naszą architekturę. Aby uzyskać więcej informacji na temat sposobu konfigurowania projektów, wytycznych dotyczących uwierzytelniania i rozpoczynania pracy, zobacz następujące artykuły:

Diagram przedstawiający sposób integracji zestawu SDK sieci szkieletowej z siecią szkieletową.

Fronton ustanawia komunikację z portalem frontonu sieci szkieletowej za pośrednictwem elementu iFrame. Portal z kolei współdziała z zapleczem sieci szkieletowej, wykonując wywołania do uwidocznionych publicznych interfejsów API.

W przypadku interakcji między polem programowania zaplecza a zapleczem sieci szkieletowej usługa Azure Relay służy jako kanał. Ponadto pole programistyczne zaplecza bezproblemowo integruje się z usługą Lakehouse. Komunikacja jest ułatwiana przy użyciu usługi Azure Relay i zestawu SDK (Fabric Software Development Kit) zainstalowanego w polu programowania zaplecza.

Uwierzytelnianie dla całej komunikacji w tych składnikach jest zapewniane za pośrednictwem firmy Microsoft Entra. Firma Microsoft Entra zapewnia bezpieczne i uwierzytelnione środowisko interakcji między frontonem, zapleczem, usługą Azure Relay, zestawem SDK sieci szkieletowej i usługą Lakehouse.

Wymagania wstępne

Zestaw SDK platformy .NET 7.0
Visual Studio 2022

Upewnij się, że Menedżer pakietów NuGet jest zintegrowana z instalacją programu Visual Studio. To narzędzie jest wymagane do usprawnionego zarządzania bibliotekami zewnętrznymi i pakietami niezbędnymi dla naszego projektu.

Zarządzanie pakietami NuGet

<NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile> i <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>: Te właściwości określają ścieżkę do plików NuSpec używanych do tworzenia pakietu NuGet dla trybów debugowania i wydawania. Plik NuSpec zawiera metadane dotyczące pakietu, takie jak jego identyfikator, wersja, zależności i inne istotne informacje.
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>: w przypadku ustawienia truewartości ta właściwość instruuje proces kompilacji, aby automatycznie wygenerował pakiet NuGet podczas każdej kompilacji. Ta właściwość jest przydatna, aby upewnić się, że pakiet jest zawsze aktualny wraz z najnowszymi zmianami w projekcie.
<IsPackable>true</IsPackable>: W przypadku ustawienia truewartości ta właściwość wskazuje, że projekt można spakować do pakietu NuGet. Tworzenie pakietów jest niezbędną właściwością dla projektów, które mają na celu tworzenie pakietów NuGet podczas procesu kompilacji.

Wygenerowany pakiet NuGet dla trybu debugowania znajduje się w katalogu src\bin\Debug po zakończeniu procesu kompilacji.

Podczas pracy w trybie chmury możesz zmienić konfigurację kompilacji programu Visual Studio na Wydanie i skompilować pakiet. Wygenerowany pakiet znajduje się w src\bin\Release katalogu . Aby uzyskać więcej informacji, zobacz Praca w trybie chmury — przewodnik.

Zależności

Przykład backend Boilerplate zależy od następujących pakietów zestawu Azure SDK:
- Azure.Core
- Azure.Identity
- Azure.Storage.Files.DataLake
- Pakiet tożsamości firmy Microsoft

Aby skonfigurować Menedżer pakietów NuGet, przed rozpoczęciem procesu kompilacji określ ścieżkę w sekcji Źródła pakietów.

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

Rozpocznij

Aby skonfigurować przykładowy projekt obciążenia na komputerze lokalnym:

Sklonuj repozytorium: uruchom polecenie git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample.git.
W programie Visual Studio 2022 otwórz rozwiązanie.
Skonfiguruj rejestrację aplikacji, postępując zgodnie z instrukcjami w samouczku uwierzytelniania. Upewnij się, że zarówno projekty frontonu, jak i zaplecza mają niezbędną konfigurację opisaną w artykule. Firma Microsoft Entra służy do bezpiecznego uwierzytelniania, aby zapewnić, że wszystkie interakcje w architekturze są autoryzowane i bezpieczne.
Zaktualizuj podstawowy adres URL systemu plików DFS usługi Microsoft OneLake. W zależności od środowiska sieci szkieletowej może być możliwe zaktualizowanie wartości w OneLakeDFSBaseURL folderze src\Constants . Wartość domyślna to onelake.dfs.fabric.microsoft.com, ale możesz zaktualizować adres URL w celu odzwierciedlenia środowiska. Aby uzyskać więcej informacji na temat ścieżek systemu plików DFS, zobacz dokumentację usługi OneLake.
Skonfiguruj konfigurację obciążenia.
1. Skopiuj workload-dev-mode.json z pliku src/Config do katalogu C:.
2. W pliku workload-dev-mode.json zaktualizuj następujące pola, aby odpowiadały konfiguracji:
  - WorkspaceGuid: Identyfikator obszaru roboczego. Tę wartość można znaleźć w adresie URL przeglądarki po wybraniu obszaru roboczego w sieci szkieletowej. Na przykład https://app.powerbi.com/groups/<WorkspaceID>/.
  - ManifestPackageFilePath: lokalizacja pakietu manifestu. Podczas kompilowania rozwiązania zapisuje pakiet manifestu w pliku src\bin\Debug. Więcej informacji o pakiecie manifestu znajduje się w dalszej części artykułu.
  - WorkloadEndpointURL: adres URL punktu końcowego obciążenia.
3. W pliku Packages/manifest/WorkloadManifest.xml zaktualizuj następujące pola, aby pasować do konfiguracji:
  - <AppId>: identyfikator klienta (identyfikator aplikacji) obciążenia aplikacji Microsoft Entra.
  - <RedirectUri>: identyfikatory URI przekierowania. Tę wartość można znaleźć w utworzonej rejestracji aplikacji w obszarze Uwierzytelnianie.
  - <ResourceId>: odbiorcy przychodzących tokenów firmy Microsoft Entra. Te informacje można znaleźć w utworzonej rejestracji aplikacji w obszarze Uwidacznianie interfejsu API.
4. W pliku src/appsettings.json zaktualizuj następujące pola, aby odpowiadały konfiguracji:
  - PublisherTenantId: identyfikator dzierżawy wydawcy obciążenia.
  - ClientId: identyfikator klienta (identyfikator aplikacji) obciążenia aplikacji Microsoft Entra.
  - ClientSecret: wpis tajny dla obciążenia aplikacji Microsoft Entra.
  - Odbiorcy: odbiorcy przychodzących tokenów firmy Microsoft Entra. Te informacje można znaleźć w utworzonej rejestracji aplikacji w obszarze Uwidacznianie interfejsu API. To ustawienie jest również nazywane identyfikatorem URI identyfikatora aplikacji.
Generowanie pakietu manifestu.

Aby wygenerować plik pakietu manifestu, skompiluj Fabric_Extension_BE_Boilerplate. Kompilacja to trzyetapowy proces, który generuje plik pakietu manifestu. Uruchamia on następujące kroki:
1. Wyzwala plik ManifestValidator.ps1 w WorkloadManifest.xml w folderze Packages\manifest/ i wyzwala element ItemManifestValidator.ps1 we wszystkich elementach XMLs (na przykład Item1.xml) w folderze Packages\manifest/. Jeśli walidacja nie powiedzie się, zostanie wygenerowany plik błędu. Skrypty sprawdzania poprawności można wyświetlić w pliku ValidationScripts/.
2. Jeśli plik błędu istnieje, kompilacja kończy się niepowodzeniem z błędem Walidacja błędów z manifestami lub wartościami domyślnymi. Aby wyświetlić plik błędu w programie Visual Studio, kliknij dwukrotnie błąd w wynikach walidacji.
3. Po pomyślnej weryfikacji spakuj pliki WorkloadManifest.xml i Item1.xml do pliku ManifestPackage.1.0.0.nupkg. Wynikowy pakiet znajduje się w pliku src\bin\Debug.
Skopiuj plik ManifestPackage.1.0.0.nupkg do ścieżki zdefiniowanej w pliku konfiguracji workload-dev-mode.json.
Program.cs to punkt wejścia i skrypt uruchamiania aplikacji. W tym pliku można skonfigurować różne usługi, zainicjować aplikację i uruchomić hosta internetowego.
Skompiluj, aby upewnić się, że projekt ma dostęp do wymaganych zależności na potrzeby kompilacji i wykonywania.
Pobieranie aplikacji DevGateway z Centrum pobierania firmy Microsoft
Uruchom aplikację Microsoft.Fabric.Workload.DevGateway.exe i zaloguj się przy użyciu użytkownika z uprawnieniami administratora obszaru roboczego dla obszaru roboczego określonego WorkspaceGuid w polu workload-dev-mode.json.

Po uwierzytelnieniu obciążenia zewnętrzne ustanawiają komunikację z zapleczem sieci szkieletowej za pośrednictwem usługi Azure Relay. Ten proces obejmuje rejestrację przekaźnika i zarządzanie komunikacją, które jest obsługiwane przez wyznaczony węzeł serwera proxy. Pakiet zawierający manifest obciążenia jest przekazywany i publikowany.

Na tym etapie sieć szkieletowa wykrywa obciążenie i uwzględnia przydzieloną pojemność.

W konsoli programu można monitorować potencjalne błędy.

Jeśli nie zostaną wyświetlone żadne błędy, połączenie zostanie nawiązane, rejestracja zostanie wykonana pomyślnie, a manifest obciążenia zostanie systematycznie przekazany.
W programie Visual Studio zmień projekt startowy na projekt Boilerplate i wybierz pozycję Uruchom.

Praca z przykładowym projektem Boilerplate

Generowanie kodu

Do zademonstrowania sposobu kompilowania obciążenia przy użyciu interfejsów API REST użyjemy przykładu boilerplate języka C# ASP.NET Core. Przykład rozpoczyna się od generowania wycinków serwera i klas kontraktów na podstawie specyfikacji struktury Swagger interfejsu API obciążenia. Kod można wygenerować przy użyciu dowolnego z kilku narzędzi do generowania kodu struktury Swagger. W przykładzie Boilerplate użyto NSwag. Przykład zawiera skrypt wiersza polecenia GenerateServerStub.cmd , który opakowuje generator kodu NSwag. Skrypt przyjmuje pojedynczy parametr, który jest pełną ścieżką do katalogu instalacyjnego NSwag. Sprawdza również plik definicji struktury Swagger (swagger.json) i plik konfiguracji (nswag.json) w folderze.

Wykonanie tego skryptu powoduje utworzenie pliku C# o nazwie WorkloadAPI_Generated.cs. Zawartość tego pliku może być logicznie podzielona na trzy części, jak wyjaśniono w następnych sekcjach.

kontrolery wycinków ASP.NET Core

ItemLifecycleController klasy i JobsController to elastyczne implementacje kontrolerów ASP.NET Core dla dwóch podzestawów interfejsu API obciążenia: zarządzanie cyklem życia elementów i zadania. Te klasy podłączają się do potoku HTTP platformy ASP.NET Core. Służą one jako punkty wejścia dla metod interfejsu API zdefiniowanych w specyfikacji struktury Swagger. Klasy przekazują wywołania do "rzeczywistej" implementacji dostarczonej przez obciążenie.

Oto przykład CreateItem metody:

/// <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);
}

Interfejsy implementacji obciążenia

IItemLifecycleController i IJobsController są interfejsami dla wcześniej wymienionych "rzeczywistych" implementacji. Definiują one te same metody, które implementują kontrolery.

Definicja klas kontraktów

Klasy kontraktów języka C# to klasy używane przez interfejsy API.

Implementacja

Następnym krokiem po wygenerowaniu kodu jest implementacja IItemLifecycleController interfejsów i IJobsController . W przykładzie ItemLifecycleControllerImpl Boilerplate i JobsControllerImpl zaimplementuj te interfejsy.

Na przykład ten kod jest implementacją interfejsu 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);
}

Obsługa ładunku elementu

Kilka metod interfejsu API akceptuje różne typy "ładunku" w ramach treści żądania lub zwracają ładunki w ramach odpowiedzi. Na przykład CreateItemRequest ma creationPayload właściwość .

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

Typy tych właściwości ładunku są definiowane w specyfikacji struktury Swagger. Istnieje dedykowany typ dla każdego rodzaju ładunku. Te typy nie definiują żadnych określonych właściwości i umożliwiają uwzględnianie żadnej właściwości.

Oto przykład CreateItemPayload typu:

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

Wygenerowane klasy kontraktów języka C# są definiowane jako partial. Mają słownik ze zdefiniowanymi właściwościami.

Oto przykład:

/// <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; }
 }
}

Kod może użyć tego słownika do odczytywania i zwracania właściwości. Lepszym rozwiązaniem jest jednak zdefiniowanie określonych właściwości przy użyciu odpowiednich typów i nazw. Deklarację partial wygenerowanych klas można użyć do wydajnego definiowania właściwości.

Na przykład plik CreateItemPayload.cs zawiera uzupełniającą definicję klasy CreateItemPayload .

W tym przykładzie definicja dodaje Item1Metadata właściwość :

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

Jeśli jednak obciążenie obsługuje wiele typów elementów, CreateItemPayload klasa musi być w stanie obsłużyć różne typy ładunków tworzenia na jeden typ elementu. Dostępne są dwie opcje. Najprostszym sposobem użycia w przykładzie Boilerplate jest zdefiniowanie wielu opcjonalnych właściwości, z których każdy reprezentuje ładunek tworzenia dla innego typu elementu. Każde żądanie ma wtedy tylko jeden z tych zestawów właściwości, zgodnie z tworzonym typem elementu. Alternatywnie można zaimplementować serializacji polimorficznej, ale ta opcja nie jest pokazana w próbce, ponieważ opcja nie zapewnia żadnych znaczących korzyści.

Aby na przykład obsługiwać dwa typy elementów, definicja klasy musi być rozszerzona tak jak w poniższym przykładzie:

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

Uwaga

Ładunek wysyłany do obciążenia jest generowany przez klienta. Może to być edytor elementów iFrame lub interfejs API REST automatyzacji sieci szkieletowej. Klient jest odpowiedzialny za wysyłanie poprawnego ładunku i dopasowywanie typu elementu. Obciążenie jest odpowiedzialne za weryfikację. Sieć szkieletowa traktuje ten ładunek jako nieprzezroczystym obiekt i przenosi go tylko z klienta do obciążenia. Podobnie w przypadku ładunku zwróconego przez obciążenie do klienta jest on odpowiedzialny za obciążenie i klienta w celu prawidłowego obsługi ładunku.

Na przykład ten kod pokazuje, jak implementacja przykładowego elementu Boilerplate1 obsługuje ładunek:

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();
}

Rozwiązywanie problemów i debugowanie

W następnych sekcjach opisano sposób rozwiązywania problemów i debugowania wdrożenia.

Znane problemy i rozwiązania

Uzyskaj informacje o znanych problemach i sposobach ich rozwiązywania.

Brak wpisu tajnego klienta

Błąd:

Microsoft.Identity.Client.MsalServiceException: Problem z konfiguracją uniemożliwia uwierzytelnianie. Sprawdź komunikat o błędzie z serwera, aby uzyskać szczegółowe informacje. Konfigurację można zmodyfikować w portalu rejestracji aplikacji. Zobacz https://aka.ms/msal-net-invalid-client , aby uzyskać szczegółowe informacje.

Oryginalny wyjątek: AADSTS7000215: podano nieprawidłowy wpis tajny klienta. Upewnij się, że wpis tajny, który jest wysyłany w żądaniu, jest wartością klucza tajnego klienta, a nie identyfikatorem wpisu tajnego klienta dodanego do ustawienia aplikacji app_guid .

Rozwiązanie: upewnij się, że masz prawidłowy klucz tajny klienta zdefiniowany w appsettings.json.

Błąd:

Microsoft.Identity.Client.MsalUiRequiredException: AADSTS65001: Użytkownik lub administrator nie wyraził zgody na korzystanie z aplikacji o identyfikatorze <example ID>. Wyślij interakcyjne żądanie autoryzacji dla tego użytkownika i zasobu.

Rozwiązanie:

W edytorze elementów przejdź do dołu strony i wybierz pozycję Przejdź do strony uwierzytelniania.
W obszarze Zakresy wprowadź wartość domyślną, a następnie wybierz pozycję Pobierz token dostępu.
W oknie dialogowym zatwierdź poprawkę.

Tworzenie elementu kończy się niepowodzeniem z powodu wyboru pojemności

Błąd:

PriorityPlacement: nie są dostępne żadne podstawowe usługi do umieszczania priorytetów. Dostępne są tylko namewartości , guidi workload-name .

Rozwiązanie:

Jako użytkownik możesz mieć dostęp tylko do pojemności próbnej. Upewnij się, że używasz pojemności, do której masz dostęp.

Błąd tworzenia pliku z błędem 404 (NotFound)

Błąd:

Tworzenie nowego pliku nie powiodło się dla ścieżki filePath: "workspace-id"/'lakehouse-id'/Files/data.json. Kod stanu odpowiedzi nie wskazuje powodzenia: 404 (NotFound).

Rozwiązanie:

Upewnij się, że pracujesz z adresem URL systemu plików DFS usługi OneLake pasujących do twojego środowiska. Jeśli na przykład pracujesz ze środowiskiem ochrony środowiska, zmień Constants.cs EnvironmentConstants.OneLakeDFSBaseUrl na odpowiedni adres URL.

Debugowanie

Podczas rozwiązywania problemów z różnymi operacjami można ustawić punkty przerwania w kodzie, aby analizować i debugować zachowanie. Wykonaj następujące kroki, aby uzyskać skuteczne debugowanie:

Otwórz kod w środowisku projektowym.
Przejdź do odpowiedniej funkcji obsługi operacji (na przykład OnCreateFabricItemAsync dla operacji CRUD lub punktu końcowego w kontrolerze dla execute operacji).
Umieść punkty przerwania w określonych wierszach, w których chcesz sprawdzić kod.
Uruchom aplikację w trybie debugowania.
Wyzwól operację z frontonu, który chcesz debugować.

Debuger wstrzymuje wykonywanie w określonych punktach przerwania, aby można było badać zmienne, przechodzić przez kod i identyfikować problemy.

Zrzut ekranu przedstawiający przykładowy program z punktami przerwania na potrzeby debugowania.

Obszar roboczy

Jeśli łączysz zaplecze z przykładowym projektem obciążenia, element musi należeć do obszaru roboczego skojarzonego z pojemnością. Domyślnie obszar roboczy Mój obszar roboczy nie jest skojarzony z pojemnością. W przeciwnym razie może zostać wyświetlony błąd pokazany na poniższym zrzucie ekranu:

Zrzut ekranu przedstawiający interfejs użytkownika na potrzeby nazewnictwa przykładowego elementu obciążenia.

Przejdź do nazwanego obszaru roboczego. Pozostaw domyślną nazwę obszaru roboczego Mój obszar roboczy.
Z prawidłowego obszaru roboczego załaduj przykładowe obciążenie i kontynuuj testy:

Współtworzenie

Zapraszamy do udziału w tym projekcie. Jeśli znajdziesz jakiekolwiek problemy lub chcesz dodać nowe funkcje, wykonaj następujące kroki:

Rozwidlenie repozytorium.
Utwórz nową gałąź dla funkcji lub poprawki błędów.
Wprowadź zmiany, a następnie zatwierdź je.
Wypchnij zmiany do rozwidlenia repozytorium.
Utwórz żądanie ściągnięcia, które zawiera jasny opis zmian.

Udostępnij za pośrednictwem

Implementowanie zaplecza usługi Microsoft Fabric

Fronton

Zaplecze

Azure Relay i DevGateway

Integracja usługi Lakehouse

Uwierzytelnianie i zabezpieczenia

Wymagania wstępne

Zarządzanie pakietami NuGet

Zależności

Rozpocznij

Praca z przykładowym projektem Boilerplate

Generowanie kodu

kontrolery wycinków ASP.NET Core

Interfejsy implementacji obciążenia

Definicja klas kontraktów

Implementacja

Obsługa ładunku elementu

Rozwiązywanie problemów i debugowanie

Znane problemy i rozwiązania

Brak wpisu tajnego klienta

Tworzenie elementu kończy się niepowodzeniem z powodu wyboru pojemności

Błąd tworzenia pliku z błędem 404 (NotFound)

Debugowanie

Obszar roboczy

Współtworzenie

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Implementowanie zaplecza usługi Microsoft Fabric

Fronton

Zaplecze

Azure Relay i DevGateway

Integracja usługi Lakehouse

Uwierzytelnianie i zabezpieczenia

Wymagania wstępne

Zarządzanie pakietami NuGet

Zależności

Rozpocznij

Praca z przykładowym projektem Boilerplate

Generowanie kodu

kontrolery wycinków ASP.NET Core

Interfejsy implementacji obciążenia

Definicja klas kontraktów

Implementacja

Obsługa ładunku elementu

Rozwiązywanie problemów i debugowanie

Znane problemy i rozwiązania

Brak wpisu tajnego klienta

Błąd podczas tworzenia elementu z powodu braku zgody administratora

Tworzenie elementu kończy się niepowodzeniem z powodu wyboru pojemności

Błąd tworzenia pliku z błędem 404 (NotFound)

Debugowanie

Obszar roboczy

Współtworzenie

Powiązana zawartość

Opinia

Dodatkowe zasoby