Microsoft Fabric 백 엔드 구현

아티클
11/24/2024

이 Microsoft Fabric 워크로드 개발 샘플 리포지토리 는 다양한 서비스와의 통합이 필요한 애플리케이션을 빌드하고 Lakehouse 아키텍처와 통합하기 위한 시작점입니다. 이 문서는 환경을 설정하고 시작하는 데 필요한 구성 요소를 구성하는 데 도움이 됩니다. 이 문서에서는 아키텍처의 주요 구성 요소 및 해당 역할에 대해 간략하게 설명합니다.

프론트엔드

프런트 엔드는 UX(사용자 환경) 및 동작을 관리하는 위치입니다. 원활한 상호 작용을 용이하게 하기 위해 iFrame을 통해 패브릭 프런트 엔드 포털과 통신합니다.

자세한 내용은 Microsoft Fabric 워크로드 개발 키트 프런트 엔드를 참조 하세요.

백엔드

백 엔드에서는 데이터와 메타데이터를 모두 저장합니다. CRUD(만들기, 읽기, 업데이트 및 삭제) 작업을 사용하여 워크로드 항목 및 메타데이터를 만들고 작업을 실행하여 스토리지에 데이터를 채웁니다. 프런트 엔드와 백 엔드 간의 통신은 공용 API를 통해 설정됩니다.

Azure Relay 및 DevGateway

Azure Relay를 사용하면 로컬 개발 환경과 패브릭 백 엔드 간의 통신을 개발자 모드로 사용할 수 있습니다. 개발자 모드에서 워크로드는 개발자의 컴퓨터에서 작동합니다.

DevGateway 유틸리티에는 다음 두 가지 역할이 있습니다.

Azure Relay 채널의 워크로드 쪽을 처리하고 특정 작업 영역의 컨텍스트에서 Fabric을 사용하여 워크로드 로컬 인스턴스의 등록을 관리합니다. 이 유틸리티는 채널 연결이 끊어지면 등록 취소를 처리합니다.
Azure Relay와 함께 작동하여 패브릭에서 워크로드로 워크로드 API 호출을 채널합니다.

워크로드 제어 API 호출은 워크로드에서 패브릭으로 직접 이루어집니다. 호출에는 Azure Relay 채널이 필요하지 않습니다.

레이크하우스 통합

워크로드 개발 키트 아키텍처는 데이터 저장, 읽기 및 가져오기와 같은 작업을 위해 Lakehouse 아키텍처와 원활하게 통합됩니다. 상호 작용은 보안 및 인증된 통신을 보장하기 위해 Azure Relay 및 Fabric SDK를 통해 촉진됩니다. 자세한 내용은 고객 데이터 작업을 참조 하세요.

인증 및 보안

Microsoft Entra ID가 보안 인증에 사용되어 아키텍처 내 모든 상호 작용에 권한이 부여되고 안전하도록 보장합니다.

개발 키트 개요는 아키텍처를 엿볼 수 있도록 합니다. 프로젝트 구성 방법, 인증 지침 및 시작 방법에 대한 자세한 내용은 다음 문서를 참조하세요.

Fabric SDK가 Fabric과 통합되는 방법을 보여 주는 다이어그램

프런트 엔드는 iFrame을 통해 Fabric 프런트 엔드 포털과의 통신을 설정합니다. 포털은 노출된 공용 API를 호출하여 패브릭 백 엔드와 상호 작용합니다.

백 엔드 개발 상자와 Fabric 백 엔드 간 상호 작용을 위해 Azure Relay는 도관 역할을 합니다. 또한 백 엔드 개발 상자는 레이크하우스와 원활하게 통합됩니다. 백 엔드 개발 상자에 설치된 Azure Relay 및 Fabric SDK(소프트웨어 개발 키트)를 사용하여 통신을 용이하게 합니다.

이러한 구성 요소 내 모든 통신에 대한 인증은 Microsoft Entra를 통해 보장됩니다. Microsoft Entra는 프런트 엔드, 백 엔드, 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>: 이러한 속성은 디버그 및 릴리스 모드에서 NuGet 패키지를 만드는 데 사용되는 NuSpec 파일의 경로를 지정합니다. NuSpec 파일에는 ID, 버전, 종속성 및 기타 관련 정보와 같은 패키지에 대한 메타데이터가 포함되어 있습니다.
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>: 로 true설정하면 이 속성은 빌드 프로세스에 각 빌드 중에 NuGet 패키지를 자동으로 생성하도록 지시합니다. 이 속성은 프로젝트의 최신 변경 내용을 사용하여 패키지를 항상 최신 상태로 유지하는 데 유용합니다.
<IsPackable>true</IsPackable>: 로 설정 true하면 이 속성은 프로젝트를 NuGet 패키지로 패키징할 수 있음을 나타냅니다. 압축 가능은 빌드 프로세스 중에 NuGet 패키지를 생성하기 위한 프로젝트의 필수 속성입니다.

디버그 모드에 대해 생성된 NuGet 패키지는 빌드 프로세스 후 src\bin\Debug 디렉터리에 있습니다.

클라우드 모드에서 작업하는 경우 Visual Studio 빌드 구성을 릴리스로 변경하고 패키지를 빌드할 수 있습니다. 생성된 패키지는 src\bin\Release 디렉터리에 있습니다. 자세한 내용은 클라우드 모드에서 작업 가이드를 참조 하세요.

종속성

백 엔드 상용구 샘플은 다음 Azure SDK 패키지에 따라 달라집니다.
- Azure.Core
- Azure.Identity
- Azure.Storage.Files.DataLake
- Microsoft ID 패키지

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에서 솔루션을 엽니다.
인증 자습서의 지침에 따라 앱 등록을 설정합니다. 프런트 엔드 및 백 엔드 프로젝트 모두 문서에 설명된 필요한 설정이 있는지 확인합니다. Microsoft Entra는 보안 인증에 사용되어 아키텍처 내의 모든 상호 작용에 권한이 부여되고 안전하게 보호되도록 합니다.
Microsoft OneLake DFS 기본 URL을 업데이트합니다. 패브릭 환경에 따라 src\ConstantsOneLakeDFSBaseURL값을 업데이트할 수 있습니다. 기본값은 onelake.dfs.fabric.microsoft.com/>이지만 환경을 반영하도록 URL을 업데이트할 수 있습니다. DFS 경로에 대한 자세한 내용은 OneLake 설명서를 참조 하세요.
워크로드 구성을 설정합니다.
1. src/Config에서 C:로 workload-dev-mode.json 복사합니다.
2. workload-dev-mode.json 파일에서 구성과 일치하도록 다음 필드를 업데이트합니다.
  - WorkspaceGuid: 작업 영역 ID입니다. Fabric에서 작업 영역을 선택하면 브라우저 URL에서 이 값을 찾을 수 있습니다. 예들 들어 https://app.powerbi.com/groups/<WorkspaceID>/입니다.
  - ManifestPackageFilePath: 매니페스트 패키지의 위치. 솔루션을 빌드하면 매니페스트 패키지가 src\bin\Debug에 저장됩니다. 매니페스트 패키지에 대한 자세한 내용은 이 문서의 뒷부분에서 제공합니다.
  - WorkloadEndpointURL: 워크로드 엔드포인트 URL입니다.
3. 패키지/매니페스트/WorkloadManifest.xml 파일에서 구성과 일치하도록 다음 필드를 업데이트합니다.
  - <AppId>: 워크로드 Microsoft Entra 애플리케이션의 클라이언트 ID(애플리케이션 ID)입니다.
  - <RedirectUri>: 리디렉션 URI입니다. 이 값은 사용자가 만든 앱 등록의 인증에서 찾을 수 있습니다.
  - <ResourceId>: 들어오는 Microsoft Entra 토큰의 대상 그룹입니다. 만든 앱 등록의 API 노출에서 이 정보를 찾을 수 있습니다.
4. src/appsettings.json 파일에서 구성과 일치하도록 다음 필드를 업데이트합니다.
  - PublisherTenantId: 워크로드 게시자 테넌트의 ID.
  - ClientId: 워크로드 Microsoft Entra 애플리케이션의 클라이언트 ID(애플리케이션 ID)입니다.
  - ClientSecret: 워크로드 Microsoft Entra 애플리케이션의 비밀.
  - 대상 그룹: 들어오는 Microsoft Entra 토큰의 대상 그룹입니다. 만든 앱 등록의 API 노출에서 이 정보를 찾을 수 있습니다. 이 설정을 애플리케이션 ID URI라고도 합니다.
매니페스트 패키지를 생성합니다.

매니페스트 패키지 파일을 생성하려면 Fabric_Extension_BE_Boilerplate 빌드합니다. 빌드는 매니페스트 패키지 파일을 생성하는 3단계 프로세스입니다. 다음 단계를 실행합니다.
1. Packages\manifest/의 WorkloadManifest.xml ManifestValidator.ps1 을 트리거하고 Packages\manifest/의 모든 항목 XML(예: Item1.xml)에서 ItemManifestValidator.ps1을 트리거합니다. 유효성 검사에 실패하면 오류 파일이 생성됩니다. ValidationScripts/에서 유효성 검사 스크립트를 볼 수 있습니다.
2. 오류 파일이 있는 경우 매니페스트 또는 기본값이 있는 오류 유효성 검사 오류와 함께 빌드가 실패합니다. Visual Studio에서 오류 파일을 보려면 유효성 검사 결과에서 오류를 두 번 클릭합니다.
3. 유효성 검사에 성공하면 WorkloadManifest.xml 패키지하고 파일을 ManifestPackage.1.0.0.nupkg에 Item1.xml. 결과 패키지는 src\bin\Debug에 있습니다.
ManifestPackage.1.0.0.nupkg 파일을 workload-dev-mode.json 구성 파일에 정의된 경로에 복사합니다.
Program.cs는 애플리케이션의 진입점 및 시작 스크립트입니다. 이 파일에서는 다양한 서비스를 구성하고, 애플리케이션을 초기화하며, 웹 호스트를 시작할 수 있습니다.
프로젝트가 컴파일 및 실행에 필요한 종속성에 액세스할 수 있도록 빌드합니다.
Microsoft 다운로드 센터에서 DevGateway를 다운로드합니다.
Microsoft.Fabric.Workload.DevGateway.exe 애플리케이션을 실행하고 workload-dev-mode.json 필드에 지정된 작업 영역에 대한 작업 영역 관리자 권한이WorkspaceGuid로 로그인합니다.

인증 후 외부 워크로드는 Azure Relay를 통해 Fabric 백 엔드와의 통신을 설정합니다. 이 프로세스에는 지정된 프록시 노드에서 용이하게 하는 릴레이 등록 및 통신 관리가 포함됩니다. 워크로드 매니페스트가 포함된 패키지가 업로드되고 게시됩니다.

이 단계에서 Fabric은 워크로드를 검색하고 할당된 용량을 통합합니다.

콘솔에서 잠재적인 오류를 모니터링할 수 있습니다.

오류가 표시되지 않으면 연결이 설정되고 등록이 성공적으로 실행되며 워크로드 매니페스트가 체계적으로 업로드됩니다.
Visual Studio에서 시작 프로젝트를 상용구 프로젝트로 변경하고 실행을 선택합니다.

상용구 샘플 프로젝트 작업

코드 생성

워크로드 상용구 C# ASP.NET Core 샘플을 사용하여 REST API를 사용하여 워크로드를 빌드하는 방법을 보여 줍니다. 샘플은 워크로드 API Swagger 사양에 따라 서버 스텁 및 계약 클래스를 생성하는 것으로 시작합니다. 여러 Swagger 코드 생성 도구를 사용하여 코드를 생성할 수 있습니다. 상용구 샘플은 NSwag를 사용합니다. 샘플에는 NSwag 코드 생성기를 래핑하는 GenerateServerStub.cmd 명령줄 스크립트가 포함되어 있습니다. 스크립트는 NSwag 설치 디렉터리의 전체 경로인 단일 매개 변수를 사용합니다. 또한 폴더의 Swagger 정의 파일(swagger.json) 및 구성 파일(nswag.json)도 확인합니다.

이 스크립트를 실행하면 이름이 WorkloadAPI_Generated.cs C# 파일이 생성됩니다. 이 파일의 내용은 다음 섹션에서 설명한 대로 논리적으로 세 부분으로 나눌 수 있습니다.

ASP.NET Core 스텁 컨트롤러

ItemLifecycleController 및 JobsController 클래스는 워크로드 API의 두 하위 집합인 항목 수명 주기 관리 및 작업에 대한 ASP.NET Core 컨트롤러의 씬 구현입니다. 이러한 클래스는 ASP.NET Core HTTP 파이프라인에 연결됩니다. Swagger 사양에 정의된 API 메서드의 진입점 역할을 합니다. 클래스는 워크로드에서 제공하는 "실제" 구현으로 호출을 전달합니다.

메서드의 예는 다음과 같습니다.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 구현하는 것입니다. 상용구 샘플 ItemLifecycleControllerImplJobsControllerImpl 에서 이러한 인터페이스를 구현합니다.

예를 들어 이 코드는 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 항목 유형당 하나씩 다양한 유형의 생성 페이로드를 처리할 수 있어야 합니다. 두 가지 옵션이 있습니다. 상용구 샘플에서 사용되는 더 간단한 방법은 각각 다른 항목 유형에 대한 만들기 페이로드를 나타내는 여러 선택적 속성을 정의하는 것입니다. 그러면 모든 요청에는 생성되는 항목 유형에 따라 이러한 속성 집합 중 하나만 있습니다. 또는 다형 serialization을 구현할 수 있지만 이 옵션은 중요한 이점을 제공하지 않으므로 샘플에 표시되지 않습니다.

예를 들어 두 항목 형식을 지원하려면 다음 예제와 같이 클래스 정의를 확장해야 합니다.

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일 수 있습니다. 클라이언트는 올바른 페이로드를 보내고 항목 종류와 일치시키는 작업을 담당합니다. 워크로드는 확인을 담당합니다. Fabric은 이 페이로드를 불투명 개체로 처리하고 클라이언트에서 워크로드로만 전송합니다. 마찬가지로 워크로드에서 클라이언트로 반환되는 페이로드의 경우 워크로드 및 클라이언트가 페이로드를 올바르게 처리해야 합니다.

예를 들어 이 코드는 상용구 샘플 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 설정에 추가된 비밀에 대한 클라이언트 비밀 ID가 아니라 클라이언트 비밀 값인지 확인합니다.

해결 방법: 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).

해결 방법:

환경에 맞는 OneLake DFS URL로 작업하고 있는지 확인합니다. 예를 들어 PPE 환경에서 작업하는 경우 Constants.cs 적절한 URL로 변경 EnvironmentConstants.OneLakeDFSBaseUrl합니다.

디버그

다양한 작업 문제를 해결할 때 코드에서 중단점을 설정하여 동작을 분석하고 디버그할 수 있습니다. 효과적인 디버깅을 위해 다음 단계를 수행합니다.

개발 환경에서 코드를 엽니다.
관련 작업 처리기 함수(예 OnCreateFabricItemAsync : CRUD 작업 또는 작업을 위한 execute 컨트롤러의 엔드포인트)로 이동합니다.
코드를 검사할 특정 줄에 중단점을 배치합니다.
디버그 모드에서 애플리케이션을 실행합니다.
디버그하려는 프런트 엔드에서 작업을 트리거합니다.

디버거는 지정된 중단점에서 실행을 일시 중지하므로 변수를 검사하고 코드를 단계별로 실행하며 문제를 식별할 수 있습니다.

디버깅을 위한 중단점이 있는 샘플 프로그램의 스크린샷.

작업 영역

백 엔드를 샘플 워크로드 프로젝트에 연결하는 경우 항목이 용량과 연결된 작업 영역에 속해야 합니다. 기본적으로 내 작업 영역 작업 영역 은 용량과 연결되지 않습니다. 그렇지 않으면 다음 스크린샷에 표시된 오류가 발생할 수 있습니다.

샘플 워크로드 항목의 이름을 지정하는 UI의 스크린샷.

명명된 작업 영역으로 전환합니다. 기본 작업 영역 이름 내 작업 영역을 그대로 둡니다.
올바른 작업 영역에서 샘플 워크로드를 로드하고 테스트를 진행합니다.

기고

사용자는 이 프로젝트에 기여할 수 있습니다. 문제가 발견되거나 새 기능을 추가하려는 경우 다음 단계를 수행합니다.

리포지토리를 포크합니다.
기능 또는 버그 수정을 위한 새 분기를 만듭니다.
변경한 다음 커밋합니다.
변경 내용을 해당 포크 리포지토리에 푸시합니다.
변경 내용에 대한 명확한 설명이 있는 끌어오기 요청을 만듭니다.

다음을 통해 공유

Microsoft Fabric 백 엔드 구현

프론트엔드

백엔드

Azure Relay 및 DevGateway

레이크하우스 통합

인증 및 보안

필수 조건

NuGet 패키지 관리

종속성

시작하기

상용구 샘플 프로젝트 작업

코드 생성

ASP.NET Core 스텁 컨트롤러

워크로드 구현을 위한 인터페이스

계약 클래스 정의

구현

항목 페이로드 처리

문제 해결 및 디버그

알려진 문제 및 해결 방법

클라이언트 암호 누락

용량 선택으로 인해 항목 만들기 실패

404(NotFound) 오류로 파일 만들기 실패

디버그

작업 영역

기고

피드백

추가 리소스

다음을 통해 공유

Microsoft Fabric 백 엔드 구현

프론트엔드

백엔드

Azure Relay 및 DevGateway

레이크하우스 통합

인증 및 보안

필수 조건

NuGet 패키지 관리

종속성

시작하기

상용구 샘플 프로젝트 작업

코드 생성

ASP.NET Core 스텁 컨트롤러

워크로드 구현을 위한 인터페이스

계약 클래스 정의

구현

항목 페이로드 처리

문제 해결 및 디버그

알려진 문제 및 해결 방법

클라이언트 암호 누락

관리자 동의 누락으로 인해 항목을 만드는 동안 오류 발생

용량 선택으로 인해 항목 만들기 실패

404(NotFound) 오류로 파일 만들기 실패

디버그

작업 영역

기고

관련 콘텐츠

피드백

추가 리소스